home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
SCLIB.ARJ
/
SCL131.DOC
< prev
next >
Wrap
Text File
|
1992-01-01
|
622KB
|
19,254 lines
SCL1 C - FUNCTION LIBRARY
VERSION 3.1
REFERENCE MANUAL
COPYRIGHT (C) 1989,1990,1991 BY:
JOSE RODRIGUEZ ALVIRA
AND
JOSE R. LEBRON
TABLE OF CONTENTS
OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . 1
DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . . 1
INSTALLING SCL1 . . . . . . . . . . . . . . . . . . . . . . . 2
USING SCL1 . . . . . . . . . . . . . . . . . . . . . . . . . 2
WHAT IS SSG . . . . . . . . . . . . . . . . . . . . . . . . . 3
SCL1DEMO . . . . . . . . . . . . . . . . . . . . . . . . . . 3
ALPHABETICAL REFERENCE . . . . . . . . . . . . . . . . . . . 5
APPENDIX "A" - FILE RELATED FUNCTIONS . . . . . . . . . . . 288
APPENDIX "B" - MOUSE FUNCTIONS . . . . . . . . . . . . . . . 290
APPENDIX "C" - SCREEN RELATED FUNCTIONS . . . . . . . . . . 291
APPENDIX "D" - SCL1 HEADER FILES . . . . . . . . . . . . . . 293
APPENDIX "E" - DIALOG TYPE FUNCTIONS . . . . . . . . . . . . 294
APPENDIX "F" - EXTENDED MEMORY MANAGEMENT FUNCTIONS . . . . 304
APPENDIX "G" - EXPANDED MEMORY MANAGEMENT FUNCTIONS . . . . 306
APPENDIX "H" - KEYBOARD MACROS . . . . . . . . . . . . . . . 307
APPENDIX "I" - COMMON COMPILER AND LINKER ERRORS . . . . . . 308
APPENDIX "J" - CHARACTER DEFINITION TABLES . . . . . . . . . 309
REGISTRATION INFORMATION . . . . . . . . . . . . . . . . . . 311
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
SCL1 Version 3.1 - Reference Manual - Page i
OVERVIEW
The functions included in this package provide an enhancement to
the standard C-library functions. Extensive screen, mouse and
memory handling functions are provided that are not found in the
standard C library. Every effort has been made to exploit the PC
hardware to its maximum capacity, portability has not been a
primary goal. The library is designed to work with Microsoft and
Borland C Compilers. The Shareware version contains stand alone
small memory model libraries for both families of compilers.
You do not need to understand the internal workings of the
functions in order to take full advantage of them, all you need
to know is how to call them and how to pass the required
parameters.
SCL1 is distributed under the Shareware concept. Feel free to try
it, if you like and use the product please register your copy.
Upon registration you will receive the following:
1. The latest version of SCL1.
2. Library modules for the small, medium, compact, large
and huge (Borland version only) memory models for the
compiler of your choice.
3. SSG, a screen editor and program generator for use with
SCL1. (see the included SSG Reference Manual)
4. You will be notified of all updates and revisions.
Feel free to distribute the Shareware version of SCL1 for trial
use by others on a private non-commercial basis. The only
distribution conditions are: that the code must not be modified
or altered, and that no fee (except a nominal distribution cost)
may be charged.
DISCLAIMER
THE FUNCTIONS INCLUDED IN THIS PACKAGE ARE, TO THE BEST OF OUR
KNOWLEDGE, ORIGINAL OR USE STANDARD ACCEPTED ALGORITHMS. THIS
SOFTWARE AND MANUAL ARE SOLD "AS IS" AND WITHOUT WARRANTIES AS TO
PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER
EXPRESSED OR IMPLIED. BECAUSE OF THE VARIOUS HARDWARE AND
SOFTWARE ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO
WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.
GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE
THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT.
THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. ANY
LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT
REPLACEMENT OR REFUND OF PURCHASE PRICE.
SCL1 Version 3.1 - Reference Manual - Page 1
Feel free to send any comments or suggestions even if you do not
decide to register your copy. If you find any bugs please let us
know so that they can be traced and fixed. Please include with
your comments any relevant information, such as; hardware
configuration, description of the bug or problem and, if
possible, a section of the problem code. Currently we can only
support this program by mail or by Compuserve.
INSTALLING SCL1
The files required to install SCL1 are distributed in compressed
self-extracting files. You can use the INSTALL.EXE (not included
in the Shareware version) program to perform the installation or
you can manually decompress and copy them to the corresponding
drives or directories. Library files are named using the
following convention:
MSCL1S.LIB
^ ^
| |
Compiler <---------+ +------> Memory Model
M = Microsoft S = Small
T = Borland M = Medium
C = Compact
L = Large
H = Huge
If you are using Microsoft C or Quick C copy the library files
starting with M to the drive or directory where you have your
library files and the header file to the drive or directory where
you have your include files. If you are using one of the Borland
compilers copy the files starting with T instead.
USING SCL1
To use SCL1 make sure you include the preprocessor directive
"#include <SCL1.H>" in your source file. Several other header
files may be needed if you use key-related constants
(scl1keys.h), color definitions (scl1clor.h), expanded memory
(scl1ems.h) or extended memory (scl1xms.h). See Appendix "D" for
more information.
You can compile your programs in two different ways:
Compiling from then Command Line
Be sure to specify the correct library model in the command-
line. Check your compiler reference for more information.
Typical command-lines can be:
SCL1 Version 3.1 - Reference Manual - Page 2
cl source.c mscl1s.lib - Microsoft C
qcl source.c mscl1s.lib - Microsoft Quick-C
tcc source.c tscl1s.lib - Borland Turbo-C
Using the Microsoft's QuickC Integrated Programming
Environment
Create a program list were all your source files and the
LIBRARY NAME and PATH is specified. Read your compiler
documentation for more information.
If you are using the BorlandC or TurboC Integrated
Programming Environment
Create a Project File were all your source files and the
LIBRARY NAME. Project files are different in the TurboC and
BorlandC environments. Be sure to check your compiler's
reference manual.
In all cases make sure that the SCL1 library is specified and
that the library's memory model matches the memory model
specified to the compiler. See Appendix "I" for more information
about possible errors.
WHAT IS SSG
You can really take the most advantage of SCL1 with an auxiliary
program called SSG. SSG is a full featured screen editor and
program generator that provides the tools for building program
screens, menus, dialog screens, data entry screens, etc. After
you design your screen, you instruct SSG about the desired
operations you want to perform, such as: saving the screen
contents, making a window, clearing all or part of the screen,
making a menu, etc. Then SSG will write the C code for the
desired operations using the functions available in SCL1. You can
merge the generated code into your program. SSG will help you in
speeding the most time consuming tasks during programming. The
SSG documentation is included in the Shareware version of SCL1.
Upon registration you will receive a full working copy of SSG.
The SCL1DEMO program shows some of SSG's capabilities.
SCL1DEMO
The program SCL1DEMO demonstrates some of the functions
available. It was written using SCL1 with the help of SSG. The
best way to discover about SCL1's features is to run this demo.
To start the demo type SCL1DEMO at the DOS prompt. The source
code is sent with the registered version of SCL1 or you can
obtain it from TECH-BBS, see the registration information at the
end of this manual.
SCL1 Version 3.1 - Reference Manual - Page 3
FUNCTION REFERENCE
A uniform format has been used in the function reference.
Functions that are related have been described together. At the
top right corner of each page, the name of the function or
functions discussed in that page are shown to let you quickly
locate them. An index is provided at the end of the reference
section. The format used is as follows:
-----------------------------------------------------------------
Function Name
-----------------------------------------------------------------
Purpose: A description of what the function does.
Prototype: Function prototype. The parameters types are shown.
All the function prototypes have been included in the
header file SCL1.H so it is not necessary to declare
them in your programs.
Returns: What the function returns.
Parameters: A description of the parameters, structures, arrays,
buffers, etc. required by the function are explained.
Messages: In the dialog type functions, messages are exchanged
with the function. This section describe these
messages.
Example: An example that will further explain the function
usage. Certain functions are self explanatory and do
not require an example. File SCL1SAMP.EXE contains
the source code for most examples. This file is
included in the reagistered version of SCL1 and can
be downloaded from Tech BBS.
SCL1 Version 3.1 - Reference Manual - Page 4
ALPHABETICAL REFERENCE
-----------------------------------------------------------------
AddExtension, ChangeExtension
-----------------------------------------------------------------
Purpose: AddExtension adds an extension to a filename if it
has no extension and does not end with a period.
ChangeExtension changes a filename's extension or
adds an extension if it has none.
Prototype: char *AddExtension(char *Filename, char *Extension);
char *ChangeExtension(char *Filename,
char *Extension);
Returns: a pointer to the filename buffer.
Parameters:
Filename - char pointer to filename.
Extension - char pointer to string holding the extension.
Example:
#include <scl1.h>
char Filename[13]="FILE";
main()
{
printf("%s\n",Filename);
/* Add an extension to file */
printf("%s\n",AddExtension(Filename,"C"));
/* Change extension from "TXT" to "BAK"*/
ChangeExtension(Filename,"BAK");
printf("%s\n",Filename);
}
See also RemoveExtension
SCL1 Version 3.1 - Reference Manual - Page 5
BackgroundOff
-----------------------------------------------------------------
BackgroundOff
-----------------------------------------------------------------
Purpose: Stops a function running in the background.
Prototype: void BackgroundOff(void);
Returns: Nothing
Parameters: None
Example:
#include <process.h>
#include <stdlib.h>
#include <errno.h>
#include <scl1.h>
#include <scl1clor.h>
/* BackgroundOn/Off example. Displays a clock in top right
corner of the screen */
int hours,minutes,seconds;
char buffer[12];
int BackClock(void);
main()
{
char *p;
Cls(WHITE_BLACK,CLS_ALL);
GetTime();
hours=GT_Hours;
minutes=GT_Minutes;
seconds=GT_Seconds;
SetCurPos(2,0);
printf("A background clock will be active until you type
EXIT\n");
BackgroundOn(BackClock); /* set background function */
p=getenv("COMSPEC");
/* run command.com */
SCL1 Version 3.1 - Reference Manual - Page 6
BackgroundOff
if(p)
{
if(spawnl(P_WAIT,p,0))
{
if(errno == ENOMEM)
printf("\nNot enough memory to load COMMAND.COM\n");
else
printf("\nUnable to load COMMAND.COM\n");
}
}
else
printf("\nEnvironment Variable COMPSEC not found\n");
BackgroundOff(); /* stop background process */
ClearKeyBuf();
}
#pragma check_stack(off)
/* this function will be called 18.2 per second */
int BackClock(void)
{
int i;
static int count=18;
/* count variable is used to keep track of time. When count=
18, a second has elapsed */
if(count==18)
{
++seconds;
if(seconds == 60)
{
seconds=0;
++minutes;
if(minutes == 60)
{
minutes=0;
++hours;
if(hours == 24)
hours=0;
}
}
i=0;
SCL1 Version 3.1 - Reference Manual - Page 7
BackgroundOff
/* convert hours/minutes/seconds values to ASCII */
if(hours < 10)
{
buffer[i]='0';
++i;
}
itoa(hours,buffer+i,10);
i=3;
if(minutes < 10)
{
buffer[i]='0';
++i;
}
itoa(minutes,buffer+i,10);
i=6;
if(seconds < 10)
{
buffer[i]='0';
++i;
}
itoa(seconds,buffer+i,10);
buffer[2]=':';
buffer[5]=':';
count=0;
}
else
++count;
Box(BLACK_WHITE,0,0,69,2,78);
WriteScreen(BLACK_WHITE,70,buffer);
}
Note: It is very important to stop any background function
before returning to DOS. Failure to do so can result in a
system crash.
See also BackgroundOn.
SCL1 Version 3.1 - Reference Manual - Page 8
BackgroundOn - Beep - BigCursor
-----------------------------------------------------------------
BackgroundOn
-----------------------------------------------------------------
Purpose: Makes a function share microprocessor time with a
main process (run in the background).
Prototype: void BackgroundOn(int (*FAddress)());
Returns: Nothing
Parameter: FAddress - Pointer to the function that will be set
to run in the background.
Example: See BackgroundOff
Note: Functions that run in the background must not perform disk
or keyboard input/output or call any time or sound related
function. SCL1's screen related functions (except GSSBox) and the
standard library data manipulation functions are generally safe
for use in background mode. Background functions are called 18.2
per second. Each time they are called they should do as little as
possible and return control to the calling routine. With a
Microsoft compiler you might need to disable the compiler's stack
checking option using the "#pragma check_stack(off)" directive.
-----------------------------------------------------------------
Beep
-----------------------------------------------------------------
Purpose: Sends a beep tone to the console speaker.
Prototype: void Beep(void);
Returns: Nothing
Parameters: None
See also SoundOn, SoundOff and TSound
-----------------------------------------------------------------
BigCursor
-----------------------------------------------------------------
Purpose: Changes the cursor size to a block.
Prototype: void BigCursor(void);
Returns: Nothing
Parameters: None
SCL1 Version 3.1 - Reference Manual - Page 9
Bin2Ascii
-----------------------------------------------------------------
Bin2Ascii
-----------------------------------------------------------------
Purpose: Fills a buffer with the ASCII code of a long integer
value, adding commas, (i.e. 12,345). The buffer must
be big enough to hold all characters plus commas and
a null string terminating character.
Prototype: char *Bin2Ascii(long Number,char * Buffer);
Returns: a pointer to the buffer.
Parameters:
Number - number whose ASCII value is to be written into the
buffer (long integer).
Buffer - char pointer to the buffer to hold the ASCII string.
Example:
#include <scl1.h>
#define WIDTH 7
main()
{
long l;
char buffer[8];
int i;
l=999999;
Cls(7,CLS_ALL);
for(i=0;i < 6;++i,l/=10)
{
WriteScreenLen(7,10,10,WIDTH,Bin2Ascii(l,buffer));
GetKey();
}
}
See also SetBin2AsciiDel
SCL1 Version 3.1 - Reference Manual - Page 10
Box - GSSBox
-----------------------------------------------------------------
Box, GSSBox
-----------------------------------------------------------------
Purpose: Draws a box with one of 12 predefined types of
frames. The row and column coordinates, color and
frame type are specified. The minimum box size is 2
rows and 2 columns. It does not perform bound
checking, the box will spill out of the screen area
if the coordinates are outside the screen range. It
draws only the box's frame and does not fill the
box's interior.
GSSBox draws a box frame and fills its interior.
Three flags; Grow, Noise and Shadow can be specified.
The grow flag tells the function to draw the box with
a growing effect, the noise flag to make a swirling
noise when drawing the box, and the shadow flag to
add a shadow effect. If you do not specify a shadow
color (using the SetShadowColor function) it will be
XOR'ed to the current background color. Leave space
for the shadow characters. You can define other types
of frames using SetUserBox.
Prototype: void Box(int Color,int FrameType,int UpperRow,
int LeftCol,int LowerRow, int RightCol);
void GSSBox(int Color,int FrameType,int UpperRow,
int LeftCol,int LowerRow,int RightCol,int GrowFl,
int SoundFl,int ShadowFl);
Returns: Nothing
Parameters:
Color - color attribute for the box (integer).
FrameType - frame type, an integer value from 0 to 11 as
follows, box frame 12 selects a user defined frame:
╔═════════╗ ┌─────────┐ ╓─────────╖ ╒═════════╕ ╒════════╕
║ FRAME 0 ║ │ FRAME 1 │ ║ FRAME 2 ║ │ FRAME 3 │ │ FRAME 4│
╚═════════╝ └─────────┘ ╙─────────╜ ╘═════════╛ └────────┘
▄▄▄▄▄▄▄▄▄▄ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓
FRAME 5 ▌ FRAME 6▐ ░ FRAME 7 ░ ▒FRAME 8 ▒ ▓FRAME 9 ▓
▀▀▀▀▀▀▀▀▀▀ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓
██████████ **********
█FRAME 10█ *FRAME 11*
██████████ **********
SCL1 Version 3.1 - Reference Manual - Page 11
Box - GSSBox
UpperRow - upper row position of the box (integer).
LeftCol - left column position of the box (integer).
LowerRow - lower row position of the box (integer).
RightCol - right column position of the box (integer).
(Note: the home position is row 0, column 0.)
For GSSBox only:
GrowFl - flag to indicate a growing effect. If this value is
"1" the box will grow from its center out. If the value is
"0" the box will pop into the screen (integer).
SoundFl - flag to indicate a noise effect. If the value is
"1" when the box grows it will make a swirling noise. A value
of "0" will draw a quiet box (integer).
ShadowFl - flag to indicate a shadow effect. If the value is
"1" a shadow effect will be drawn, if the value is "0" no
shadow effect will be drawn. The shadow will be XOR'ed to the
background, if no shadow color have been defined (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=WHITE_BLACK;
main()
{
Box(Color1,6,2,18,16,67);
/* Draws a box starting in line 2, column 16 and ending in line
18, column 67 with a small solid border.*/
GSSBox(Color1,0,3,12,20,68,1,1,0);
/* Will draw a growing, shadowed, double framed box between rows
3 & 20 and columns 12 & 68 */
}
See also Shadow and SetShadowColor
SCL1 Version 3.1 - Reference Manual - Page 12
Buf2Disk - HBuf2Disk
-----------------------------------------------------------------
Buf2Disk, HBuf2Disk
-----------------------------------------------------------------
Purpose: Saves a buffer to disk. With HBuf2Disk the file size
can be larger than 64K, using the compact and large
models. HBuf2Disk's prototype is declared in
SCL1HUGE.H
Prototype: int Buf2Disk(char* Filename, char *Buffer,
unsigned int Bytes);
int HBuf2Disk(char* Filename,char huge *Buffer,
unsigned long Bytes);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Filename - filename of file to write data to (char pointer).
Buffer - buffer that holds the data to be written to disk.
Bytes - the number of bytes to write (unsigned integer for
Buf2Disk and unsigned long for HBuf2Disk).
Example:
#include <scl1.h>
char buffer[]="We'll write this data to disk and read it
back.\n";
main()
{
int Error;
unsigned int size;
if(Error=Buf2Disk("FILE.1",buffer,sizeof(buffer)))
{
printf("Error writing file # %i\n",Error);
exit(-1);
}
size=sizeof(buffer);
memset(buffer,0,size);
if(Error=File2Buf("FILE.1",buffer,&size))
printf("Error reading file # %i\n",Error);
else
printf("%s\n",buffer);
}
See also File2Buf, HFile2Buf and TrapInt24.
SCL1 Version 3.1 - Reference Manual - Page 13
Calendar
-----------------------------------------------------------------
Calendar
-----------------------------------------------------------------
Purpose: Displays a calendar. It can display it either in
english, spanish or in any other language set by
using the C_SetUserLang function. The calendar
position can be set anywhere in the screen. No bounds
checking is made.
Prototype: int Calendar(Message, CData *cd);
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. It returns messages as described below.
Parameters: Dialog type functions receive messages and structures
as parameters. The calendar information is defined in
structure CData as follows:
typedef struct{
int NColor; Normal color for the calendar
display.
int RColor; Color for displaying the selected
day.
int Row; Upper left row position of the
calendar.
int Col; Upper left column position of the
calendar.
int FrameType; Type of frame to be used, any of
the frame types that can be used
with Box.
unsigned int *ExitKeys; Null-terminated array of keys that
will exit the calendar function.
int Lang; Language. "0" for english, "1" for
spanish, "2" for any other language
(define the text with
C_SetUserLang).
int Month; Month to be displayed.
int Day; Day to be displayed (1-31).
int Year; Year to be displayed from 1900 to
2067.
SCL1 Version 3.1 - Reference Manual - Page 14
Calendar
unsigned int EventInfo; Variable that holds the key pressed
when you exit the function or a
when a non defined key is pressed.
}CData;
Messages:
The following messages can be sent to Calendar:
C_INIT - initialize the CData structure to NULL and set the
following default values:
NColor - white characters in a black background or the
normal color set by SetDialogColors.
HColor - highlighted white characters in a black
background or the highlight color set by SetDialogColors.
Col and Row - for display it in the middle of the screen.
Month, Day and Year - current system's date.
FrameType - frame type "0" (double line).
ExitKeys - defined as ENTER, ESCAPE, TAB & SHIFTAB.
C_DRAW - display the calendar using the current parameters.
C_ACTIVE - display the calendar with the current parameters
and let the user change the date using the cursor keys as
follows:
Key Action
Up Arrow cursor one day up.
Down Arrow cursor one day down.
Left Arrow cursor one day to the left.
Right Arrow cursor one day to the right.
Page Up increment the month by one.
Page Down decrement the month by one.
+ increment the year by one.
- decrement the year by one.
The date can also be changed by clicking the mouse buttons in
the calendar display.
C_CHECK_MOUSE - asks the function if the mouse has been
clicked while pointing the calendar area.
SCL1 Version 3.1 - Reference Manual - Page 15
Calendar
C_SHADOW_ON - displays a shadow effect when the calendar is
drawn.
C_SHADOW_OFF - disables the shadow effect.
C_RESET - when this message is sent the Day, Month and Year
variables are set to the system's date. If exit keys have not
been defined they are set to the default exit keys.
The following messages can be returned by Calendar:
C_OK - the action requested has been performed.
C_EXIT_KEY - a key that has been defined as an exit key has
been pressed.
C_MOUSE_EVENT - the mouse has been clicked after pointing
outside the area defined by the function.
C_ILLEGAL_KEY - a key that has not been defined has been
pressed.
C_NEW_POSITION - this message is returned every time the
month, year or day has been changed.
C_MY_MOUSE - this message is returned in response to the
C_CHECK_MOUSE message if the mouse has been pressed in the
Calendar screen area.
Example:
#include <scl1.h>
main()
{
int Mess; /* returned messages */
CData test; /* define test as type CData */
Calendar(C_INIT,&test); /* Initialize to defaults */
Calendar(C_SHADOW_ON,&test); /* Display with shadow effect*/
Calendar(C_DRAW,&test); /* Display the calendar */
do{ /* loop until exit key */
Mess=Calendar(C_ACTIVE,&test); /* browse */
}while (Mess!=C_EXIT_KEY);
}
SCL1 Version 3.1 - Reference Manual - Page 16
Center - ChangeDumpColor
-----------------------------------------------------------------
Center
-----------------------------------------------------------------
Purpose: Centers a string horizontally.
Prototype: int Center(char *String);
Returns: The column position required for displaying the
string centered in the screen.
Parameter: String - pointer to the string to be centered (char).
Example:
#include <scl1.h>
main()
{
WriteString(0x7,1,Center("Main Menu"),"Main Menu");
}
-----------------------------------------------------------------
ChangeDumpColor
-----------------------------------------------------------------
Purpose: Changes the color attributes of a ScreenDump array.
Prototype: void ChangeDumpColor(int OldColor,int NewColor,
char*Array);
Returns: Nothing
Parameters:
OldColor - color value you want to change (integer).
NewColor - new color you desire (integer).
*Array - ScreenDump array (char pointer).
Example:
#include <scl1.h>
/* Each character is followed by its color attribute, a \n can
be used to indicate new lines and a "0" is used to indicate
the end of the array */
char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0};
SCL1 Version 3.1 - Reference Manual - Page 17
ChangeDumpColor - CheckChar
main()
{
ScreenDump(10,10,Array); /* Write at line 10, column 10 */
GetKey();
ChangeDumpColor(0x70,7,Array);/*Change color from 0x70 to 7*/
ScreenDump(10,10,Array); /* Write at line 10, column 10 */
}
See also ScreenDump.
-----------------------------------------------------------------
CheckChar
-----------------------------------------------------------------
Purpose: Checks for a valid keyboard character.
Prototype: unsigned int CheckChar(unsigned int Character,
unsigned int ControlCode);
Returns: The return value is the character, if valid, or "0"
if the character is not valid.
Parameters:
Character - character to verify (unsigned integer).
ControlCode - type of character to accept (unsigned integer).
Control codes defined in SCL1.H:
CC_ANY - accept any character.
CC_LETTER - only letters.
CC_DIGIT - only digits.
CC_CAPITALIZE - capitalize.
CC_REAL - accept real numbers.
CC_FILESPEC - accept valid filename characters.
CC_ESPANOL - letters & accented characters used in
the spanish language.
CC_PUNCTUATION - accept (,;.+-* spaces,etc.).
CC_PATH - accept valid filenames and pathnames
characters.
CC_SEARCH - accept all characters of CC_PATH and
the "*" and "?" characters.
CC_EXPONENTIAL - accept numbers in exponential form.
SCL1 Version 3.1 - Reference Manual - Page 18
CheckChar - CheckEnhancedKeyb
Example:
#include<scl1.h>
#include<scl1keys.h>
main()
{
unsigned int Key;
Key=GetKey();
if (CheckChar(Key,CC_LETTER))>0)
/* Character is valid */
else
/* Character is invalid */
}
-----------------------------------------------------------------
CheckEnhancedKeyb
-----------------------------------------------------------------
Purpose: After this function is called and an enhanced
keyboard (101 keys) is detected, SCL1's keyboard
related functions will return different SCAN/ASCII
codes for the extra keys found in these keyboards
(for example; the ENTER key in the numeric keypad and
the regular ENTER key). These codes have been defined
in SCL1KEYS.H preceded by the ENH prefix. This
function also enables the detection of the F11 and
F12 function keys.
Prototype: int CheckEnhancedKeyb(void);
Returns: The return value is "1" of an enhanced keyboard is
detected or "0" if none is detected.
Example:
#include <scl1.h>
#include <scl1keys.h>
/* shows the use of CheckEnhancedKeyb function */
main()
{
unsigned int Key;
if(CheckEnhancedKeyb())
printf("\nAn enhanced keyboard has been detected\n
Press one of your ENTER keys\nor functions keys
F11-F12\nESC to exit\n");
SCL1 Version 3.1 - Reference Manual - Page 19
CheckEnhancedKeyb
else
{
printf("No Enhanced Keyboard available\n");
exit(-1);
}
/* SCL1 keyboard function will now report enhanced keyboard
extra keys */
do
{
switch(Key=GetKey())
{
case ENH_ENTER:
printf("Enhanced Enter, press the other ENTER
key\n");
break;
case ENTER:
printf("Enter, press the other ENTER key\n");
break;
case F11:
printf("F11\n");
break;
case F12:
printf("F12\n");
break;
case SHIFTF11:
printf("Shift F11\n");
break;
case SHIFTF12:
printf("Shift F12\n");
break;
case CTRLF11:
printf("Control F11\n");
break;
case CTRLF12:
printf("Control F12\n");
break;
case ALTF11:
printf("Alt F11\n");
break;
case ALTF12:
printf("Alt F12\n");
break;
default:
printf("Unknown key SCAN/ASCII Code: %X\n",Key);
break;
}
}while(Key != ESC);
}
SCL1 Version 3.1 - Reference Manual - Page 20
CheckItemList
-----------------------------------------------------------------
CheckItemList
-----------------------------------------------------------------
Purpose: Checks if the mouse has been clicked at any item in
an item list (SEE DrawItemList).
Prototype: int CheckItemList(int Number, int ItemLength,
struct ItemList *il);
Returns: The number of the item selected with the mouse (>"1")
or "0" if none has been selected.
Parameters: The item list information is given as an array of
structures as follows:
struct ItemList{
int Row; Row position of the item.
int Col; Column position of the item.
char *String; Char pointer to item text.
};
The parameters passed to the function are:
Number - number of items (integer).
ItemLength - maximum length of items (integer).
ItemList - pointer to the defined structure.
Example:
#include <scl1.h>
#include <scl1clor.h>
struct ItemList il[]={
10,10,"String 1",
10,30,"String 2",
10,50,"String 3",
};
main()
{
int Selection=0;
Cls(WHITE_BLACK,CLS_ALL);
if(CheckMouse())
InitMouse(IM_SHOW);
else
SCL1 Version 3.1 - Reference Manual - Page 21
CheckItemList - CheckMouse
{
printf("No Mouse Installed\n");
exit(-1);
}
DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
SetCurPos(14,0);
while(Selection==0)
{
if(Selection=CheckItemList(3,8,il))
{
DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il);
printf("\nOption #%i was selected\n",Selection);
}
}
exit(0);
}
NOTE: Use DrawItemList to draw an ItemList structure to the
screen. See also ListManager to integrate mouse and
keyboard. The Dialog type function ListWindow provides an
alternative way to perform the same task.
-----------------------------------------------------------------
CheckMouse
-----------------------------------------------------------------
Purpose: Determines if a mouse is installed. Sets variable
MSE_MouseFl to "1" if mouse is found.
Prototype: int CheckMouse(void);
Returns: The return value is "1" if the mouse is installed and
"0" if no mouse is installed.
Parameters: None
Example:
#include <scl1.h>
main()
{if(CheckMouse())/* do we have a mouse? */
{
/* Yes */
ResetMouse(); /* reset mouse */
SetMouseIsr();/* initialize ISR */
ShowMouse(); /* cursor on */
}
ResetMouse(); /* reset mouse before exit */
}
SCL1 Version 3.1 - Reference Manual - Page 22
CheckMouseButton
-----------------------------------------------------------------
CheckMouseButton
-----------------------------------------------------------------
Purpose: Checks if the mouse has been clicked at any mouse
button defined using the DrawMouseButton function.
Prototype: int CheckMouseButton(int Number,
struct MouseButton *p);
Returns: The number of the selected screen Mouse Button or "0"
if none has been selected.
Parameters: The Mouse Button information is specified in a
structure as follows:
struct MouseButton{
int Top; Upper row position of the Mouse Button
area.
int Left; Upper column position of the Button area.
int Bottom; Right row position of the Button area.
int Right; Right column position of the Button area.
int Row; Row position of the Mouse Button text.
int Col; Column position of the Button text.
char String[20]; Mouse Button text (maximum of 19
characters.).
};
The parameters passed to the function are:
Number - number of mouse buttons (integer).
MouseButton - pointer to defined structure.
Example:
#include <scl1.h>
#include <scl1clor.h>
SCL1 Version 3.1 - Reference Manual - Page 23
CheckMouseButton - ClearKeyBuf
struct MouseButton mb[]={
4,35,6,45,
5,39,
"YES",
10,35,12,45,
11,39,
"NO",};
main()
{
int Selection=0;
Cls(WHITE_BLACK,CLS_ALL);
if(CheckMouse())
InitMouse(IM_SHOW);
else
{
printf("No Mouse Installed\n");
exit(-1);
}
DrawMouseButton(WHITE_BLACK,BLACK_WHITE,2,Selection,mb);
SetCurPos(14,0);
while(Selection==0)
{
if(Selection=CheckMouseButton(2,mb))
{
DrawMouseButton(WHITE_BLACK,BLACK_WHITE,2,Selection,mb);
printf("\nMouse button #%i was selected\n",Selection);
}
}
exit(0);
}
See also DrawMouseButton to draw the buttons.
-----------------------------------------------------------------
ClearKeyBuf
-----------------------------------------------------------------
Purpose: Clears keyboard buffer of any character or keystroke
pending to be processed.
Prototype: void ClearKeyBuf(void);
Returns: Nothing.
Parameters: None.
SCL1 Version 3.1 - Reference Manual - Page 24
ClearWindow - ClockTick
-----------------------------------------------------------------
ClearWindow
-----------------------------------------------------------------
Purpose: Clears a window previously defined using the
InitWdata function and displayed using the
CreateWindow function.
Prototype: void ClearWindow(WData *wd);
Returns: Nothing
Parameter: WData - pointer to the WData structure.
Example: See InitWData
----------------------------------------------------------------
ClockTick
----------------------------------------------------------------
Purpose: When this function is called the program waits for
the next timer interrupt before returning control to
the calling program or function.
Prototype: void ClockTick(void);
Returns: Nothing
Parameters: None
SCL1 Version 3.1 - Reference Manual - Page 25
CloseFile
-----------------------------------------------------------------
CloseFile
-----------------------------------------------------------------
Purpose: Closes a file.
Prototype: int CloseFile(int Handle);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: Handle - Handle number given by DOS when you create
or open a file (integer).
Example:
#include <scl1.h>
/* This is the source code of the Buf2Disk function */
Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes)
{
int i,handle;
if(i=CreateFile(Filename,&handle,F_ARCHIVE))
return(i);
if(i=WriteFile(handle,Buffer,Bytes))
{
if(i > 0)
CloseFile(handle);
return(i);
}
return(CloseFile(handle));
}
SCL1 Version 3.1 - Reference Manual - Page 26
Cls
-----------------------------------------------------------------
Cls
-----------------------------------------------------------------
Purpose: Clears a screen area.
Prototype: void Cls(int Color,int UpperRow,int LeftCol,
int BottomRow,int RightCol);
Returns: Nothing
Parameters:
Color - color attribute of the area to be cleared (integer).
UpperRow - upper row position of the area to be cleared
(integer). Valid range from 0 to 24.
LeftCol - left column position of the area to be cleared
(integer). Valid range from 0 to 79.
LowerRow - lower row position of the area to be cleared.
(int).
RightCol - right column position of the area to be cleared.
(int).
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=WHITE_BLACK;
main()
{
Cls(Color1,18,0,24,79);
}
or,
main()
{
Cls(Color1,CLS_ALL);
/* CLS_ALL is defined in SCL1.H to clear the whole screen.*/
}
SCL1 Version 3.1 - Reference Manual - Page 27
CreateFile
-----------------------------------------------------------------
CreateFile
-----------------------------------------------------------------
Purpose: Creates a new file or truncates an existing file to
zero.
Prototype: int CreateFile(char *Filename,int *Handle,
int Attrib);
Returns: the DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Filename - char pointer to a valid filename.
Handle - pointer to an integer variable that will contain the
file handle number given by DOS (integer).
Attrib - type of file to create, Read only, hidden, etc.
(integer). The following types has been defined in SCL1.H:
F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME,
F_DIRECTORY, F_ARCHIVE
Example: See CloseFile
SCL1 Version 3.1 - Reference Manual - Page 28
CreateWindow - DestroyWindow - CursorOn - CursorOff
-----------------------------------------------------------------
CreateWindow, DestroyWindow
-----------------------------------------------------------------
Purpose: CreateWindow displays a window defined with a WData
structure that can be initialized using the InitWdata
function. This function can save the screen area in a
buffer, draw a frame, shadow, grow, shrink, etc.
These attributes are specified when the WData struct
is initialized.
DestroyWindow removes or deletes a window previously
defined using the CreateWindow function and restores
the screen.
Prototype: int CreateWindow(WData *wd);
void DestroyWindow(WData *wd);
Returns: CreateWindow can return one of the following messages
defined in header file SCL1.H:
W_OK if the window was created.
W_NOMEM if there is not enough memory left for the
window buffer.
DestroyWindow does not return values.
Parameter: WData - pointer to the WData structure.
Example: See InitWData
-----------------------------------------------------------------
CursorOff, CursorOn
-----------------------------------------------------------------
Purpose: Turns the cursor off (not visible), or on (visible).
Prototype: void CursorOff(void);
void CursorOn(void);
Returns: Nothing
Parameters: None
SCL1 Version 3.1 - Reference Manual - Page 29
C_SetUserLang
-----------------------------------------------------------------
C_SetUserLang
-----------------------------------------------------------------
Purpose: Lets you modify the month and week day names for the
Calendar function.
Prototype: void C_SetUserLang(CData *cd,char **data);
Returns: Nothing.
Parameters:
cd - pointer to the Calendar structure.
data - array that contains the user defined month names and
week names (refer to the example).
Example:
/* months and weeks days in French */
char *month[]={
"Janvier",
"Fevrier",
"March",
"Avril",
"May",
"June",
"Julliet",
"Aout",
"September",
"October",
"Novembre",
"Decembre",
" Dim Lun Mar Mer Jeu Ven Sam ", /* spaces are important */
};
/* A sample call to the function will be: */
C_SetUserLang(&cd,month);
SCL1 Version 3.1 - Reference Manual - Page 30
Date2Num
-----------------------------------------------------------------
Date2Num
-----------------------------------------------------------------
Purpose: Converts a date in the format Month-Day-Year to an
unsigned integer number that represents the number of
days the have elapsed since the base date (January 1,
1900, which corresponds to number 1). This conversion
saves storage space since the date is represented as
an unsigned integer. This function together with
Num2Date permits you to perform date arithmetic, like
adding x number of days to a date, etc.
Prototype: unsigned int Date2Num(int Month, int Day, int Year);
Returns: An unsigned integer which represents the date or "0"
if an invalid date is passed to the function.
Parameters:
Month - a valid month number (1 to 12) (integer).
Day - a valid day number (1 to 28,29,30 or 31) (integer).
Year - a valid year number (four digits) from 1900 to 2077
(int).
Example:
#include <scl1.h>
main()
{
int D,M,A,W;
unsigned int N;
scanf("%i",&M);
scanf("%i",&D);
scanf("%i",&A);
N=Date2Num(M,D,A);
if(N==0)
printf("Invalid Date");
else
{
printf(" %ui\n",N);
Num2Date(N,&M,&D,&A,&W);
printf(" %i,%i,%i %i",M,D,A,W);
}
}
See also Num2Date
SCL1 Version 3.1 - Reference Manual - Page 31
DaysPerMonth - DeleteFile
-----------------------------------------------------------------
DaysPerMonth
-----------------------------------------------------------------
Purpose: Returns the number of days of a given month.
Prototype: int DaysPerMonth(int year,int month);
Returns: The number of days that a given month contains.
Parameters:
Year - valid month year (4 digits) from 1900 to 2077 (int).
Month - a valid month number (1 to 12) (integer).
-----------------------------------------------------------------
DeleteFile
-----------------------------------------------------------------
Purpose: Deletes a file.
Prototype: int DeleteFile(char *Filename);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: Filename - char pointer to a valid filename.
Example:
#include <scl1.h>
main()
{
int handle,i;
i=CreateFile("SCL1.TST",&handle,F_ARCHIVE);
if(i)
{
printf("\nDOS error #%i, unable to create file\n",i);
exit(-1);
}
CloseFile(handle);
i=DeleteFile("SCL1.TST");
if(i)
{
printf("\nDOS error #%i, unable to erase file\n",i);
exit(-1);
}
exit(0);
}
SCL1 Version 3.1 - Reference Manual - Page 32
DialogBox
-----------------------------------------------------------------
DialogBox
-----------------------------------------------------------------
Purpose: Displays a dialog box at the center of the screen for
keyboard input. The function takes care or saving and
restoring the screen contents in the display area.
See the GetString function for the editing features.
Prototype: int DialogBox(int BoxColor,char *Prompt,
int InputColor,int MaxChar,
unsigned int CharType,char *Buffer);
Returns: The number of characters typed or "-1" if Esc is
pressed.
Parameters:
BoxColor - color attributes of the dialog box (integer).
Prompt - pointer to the dialog prompt (char).
InputColor - color attributes of the input (integer).
MaxChar - maximum number of characters to accept (integer).
CharType - the type of characters to accept as defined in
SCL1.H (refer to the CheckChar function) (unsigned integer).
Buffer - pointer to the buffer to be used to store the
information entered, it must be one digit larger than the
field size (for the string termination null character).
Example:
#include <scl1.h>
#include <scl1clor.h>
char buffer[33] /* buffer to hold input, one character larger
than MaxChar */
/* The following function call will display the DialogBox */
DialogBox(WHITE_BLACK,"Filename",BLACK_WHITE,32,CC_FILESPEC,
buffer);
SCL1 Version 3.1 - Reference Manual - Page 33
DisableMouse - Dissolve
-----------------------------------------------------------------
DisableMouse
-----------------------------------------------------------------
Purpose: Removes interrupt service routine installed by
SetMouseIsr
Prototype: void DisableMouse(void);
Returns: Nothing
Parameters: None
Example: See CheckMouse
-----------------------------------------------------------------
Dissolve
-----------------------------------------------------------------
Purpose: Clears the screen using special effects like; shrink
from borders to the center, horizontal shrink from
borders to center, etc. The function works in all
video modes supported by SCL1.
Prototype: void Dissolve(int Color,int Type,int Speed);
Returns: Nothing
Parameters:
Color - color to be used for clearing the screen (integer).
Type - the clearing effect to use (integer). The following
types have been defined in SCL1.h:
DS_BOX - use a shrinking effect from borders to center.
DS_SIDES - use an horizontal shrinking effect from
borders to the center.
DS_SIX_PARTS - use an horizontal shrinking effect from
left to right in six screen sections.
DS_FOUR_BOXES - same effect as DS_BOX but provides four
sections.
Speed - speed to use for the clearing effect in hundredths of
a second (integer). The recommended speed is 1 hundredths of
a second.
SCL1 Version 3.1 - Reference Manual - Page 34
Dissolve
Example:
#include <scl1.h>
#include <scl1clor.h>
/* Shows several dissolve effects for clearing the screen */
main()
{
int Color1,Color2;
if(Video()==COLOR)
{
Color1=WHITE_BLACK;
Color2=BROWN_BLACK+HIGHLIGHT;
}
else
{
Color1=WHITE_BLACK;
Color2=WHITE_BLACK+HIGHLIGHT;
}
/* Fill screen with X */
FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X');
WaitTime(50); /* 1/2 second delay */
Dissolve(Color1,DS_BOX,1); /* Clear screen */
WaitTime(50);
FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X');
WaitTime(100);
Dissolve(Color1,DS_SIDES,1);
WaitTime(50);
FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X');
WaitTime(100);
Dissolve(Color1,DS_SIX_PARTS,1);
WaitTime(50);
FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X');
WaitTime(100);
Dissolve(Color1,DS_FOUR_BOXES,1);
}
SCL1 Version 3.1 - Reference Manual - Page 35
DrawBoxLine
-----------------------------------------------------------------
DrawBoxLine
-----------------------------------------------------------------
Purpose: Draws either vertical or horizontal lines inside a
box with the proper end line characters.
Prototype: void DrawBoxLine(int Color,int FrameType,int Row1,
int Col1,int Row2,int Col2);
Returns: Nothing
Parameters:
Color - color attributes of the line to be drawn (integer).
FrameType - type of frame used to draw the box (integer).
Row1 - row position where the line starts (integer).
Col1 - column position where the line starts (integer).
Row2 - row position where the line ends (integer).
Col2 - column position where the line ends (integer).
Note: To draw horizontal lines both Row1 and Row2 must have the
same value, for vertical lines both Col1 and Col2 must
have the same value.
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=WHITE_BLACK;
main()
{
Box(Color1,0,0,0,24,79); /* Full screen box */
DrawBoxLine(Color1,0,5,0,5,79); /* Horizontal line in row 5*/
DrawBoxLine(Color1,0,5,39,24,39);/* Vertical line between rows 5
and 24 */
}
See also Box, GSSBox, DrawLine
SCL1 Version 3.1 - Reference Manual - Page 36
DrawItemList
-----------------------------------------------------------------
DrawItemList
-----------------------------------------------------------------
Purpose: Draws a list of strings to the screen and permits the
user to browse through them. The selected item (>0)
is drawn in the color specified with SelectedColor.
Prototype: void DrawItemList(int NormalColor,int SelectedColor,
int Number,int Selection,Struct ItemList *il);
Returns: Nothing
Parameters: The ItemList information must be given as an array of
structures as follows:
struct ItemList{
int Row; Row position of the item.
int Col; Column position of the item.
char *String; Char pointer to item text.
};
The parameters passed to the function are:
NormalColor - color for the normal display of items
(integer).
SelectedColor - color for the display of the selected item
(integer).
Number - number of items to be displayed (integer).
Selection - default selection to be displayed when entering
the function (integer).
ItemList - pointer to a previously defined ItemList
structure.
Example: See CheckItemList
NOTE: The ScrollWindow and ListWindow functions provide
alternatives to perform the same tasks.
SCL1 Version 3.1 - Reference Manual - Page 37
DrawLine
-----------------------------------------------------------------
DrawLine
-----------------------------------------------------------------
Purpose: Draws either vertical or horizontal lines.
Prototype: void DrawLine(int Color,int Row,int Col,int Count,
int Direction,int Character);
Returns: Nothing
Parameters:
Color - color attributes of the line to be drawn (integer).
Row - row position where the line starts (integer).
Col - column position where the line starts (integer).
Count - number of line characters to be drawn (integer).
Direction - direction to draw. Constants DL_HORIZONTAL and
DL_VERTICAL has been defined in SCL1.H.
Character - graphic character to use for line drawing (int).
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=WHITE_BLACK;
main()
{
DrawLine(Color1,5,5,10,DL_HORIZONTAL,196);
/* Horizontal line in row 5, between columns 5 and 15 */
DrawLine(Color1,5,5,14,DL_VERTICAL,179);
/* Vertical line between rows 5 and 19, column 5 */
}
SCL1 Version 3.1 - Reference Manual - Page 38
DrawMouseButton
-----------------------------------------------------------------
DrawMouseButton
-----------------------------------------------------------------
Purpose: Draws one or more Mouse Buttons. The selected button
is drawn inside a double line box. A mouse button
consists of a text prompt inside a box. You can
select the mouse button by clicking the mouse after
pointing it.
Prototype: void DrawMouseButton(int NormalColor,
int SelectedColor,int Number,int Selection,
struct MouseButton *p);
Returns: Nothing.
Parameters: The Mouse Button information must be given as an
array of structures:
struct MouseButton{
int Top; Upper row position of the Mouse Button area.
int Left; Upper column position of the Mouse Button
area.
int Bottom; Right row position of the Mouse Button area.
int Right; Right column position of the Mouse Button
area.
int Row; Row position of the Mouse Button text.
int Col; Column position of the Mouse Button text.
char String[20]; Mouse Button text (19 characters maximum)
};
The parameters passed to the function are:
NormalColor - color used when button is not selected
SelectedColor - Color used for a selected button (integer).
Number - Number of buttons in the structure (integer).
Selection - Number of the selected button (0 for none) (int).
MouseButton - pointer to predefined structure.
Example: See CheckMouseButton
SCL1 Version 3.1 - Reference Manual - Page 39
EB_SetUserLang
-----------------------------------------------------------------
EB_SetUserLang
-----------------------------------------------------------------
Purpose: Lets you modify the default prompts of the ErrorBox
function. With it you can customize the default
"Press any key to Continue" and "Unknown Error"
prompts. This is useful when writing programs in
languages other that English. Error messages can be
defined using the InitUserError function. See
ErrorBox for default messages.
Prototype: void EB_SetUserLang(char *prompt1,char *prompt2);
Returns: Nothing.
Parameters:
prompt1 - char pointer to the first prompt, whose default is
"Press any key to Continue".
prompt2 - char pointer to the second prompt, whose default is
"Unknown Error".
Example:
/* this function call sets the ErrorBox prompts to Spanish */
EB_SetUserLang("Oprima cualquier tecla para Continuar","Error
Desconocido");
SCL1 Version 3.1 - Reference Manual - Page 40
EMS_Alloc
-----------------------------------------------------------------
EMS_Alloc
-----------------------------------------------------------------
Purpose: Allocates the number of pages requested and assigns
an EMM handle to these pages. The EMM handle owns
these pages until they are deallocated.
Prototype: int EMS_Alloc(int handle,int pages);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has allocated the requested pages.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_NO_MORE_HANDLE if all EMM handles are being used.
EMS_LOG_GREATER_PH if there are not enough expanded
memory pages present in the system to satisfy the
request.
EMS_LOG_GREATER_AVA if there are not enough
unallocated pages to satisfy the request.
EMS_ZERO_ALLOC if you attempted to allocate zero
pages.
Parameters:
handle - the EMM handle your program received from a call to
the EMS_Alloc function (integer).
pages - the number of pages you want your program to allocate
(integer).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 41
EMS_AvailableLogPages
-----------------------------------------------------------------
EMS_AvailableLogPages
-----------------------------------------------------------------
Purpose: Returns the number of unallocated pages of expanded
memory.
Prototype: int EMS_AvailableLogPages(unsigned int *npages);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the number of unallocated
pages and the number of total pages in expanded
memory.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameter: npages - pointer to an unsigned int that will be set
to the number of currently available pages
(unallocated).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 42
EMS_Exchange - EMS_Move
-----------------------------------------------------------------
EMS_Exchange, EMS_Move
-----------------------------------------------------------------
Purpose: Exchanges or moves a region of memory from
conventional to conventional memory, conventional to
expanded memory, expanded to conventional memory or
expanded to expanded memory.
Prototype: int EMS_Exchange(EMSMove *);
int EMS_Move(EMSMove *);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if the memory regions have been exchanged or
moved.
EMS_NOT_IMPLEMENTED if the function code passed to
the EMS manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if the manager could not find
either the source or destination EMM handles.
EMS_INVALID_LOG if one or more of the logical pages
is out of the range of logical pages allocated to the
source/destination handle.
EMS_S_NOT_IMPLEMENTED if EMS subfunction is invalid.
EMS_SOURCE_OVERWRITTEN if the source and destination
expanded memory regions have the same handle and
overlap. This is valid for a move. The move has been
completed and the destination region has a copy of
the source region. However, at least a portion of the
source region has been overwritten by the move.
EMS_SIZE_ERROR if the length of the source or
destination expanded memory region specified exceeds
the length of the expanded memory region allocated
either the source or destination handle.
EMS_OVERLAP if the conventional memory region and
expanded memory region overlap.
SCL1 Version 3.1 - Reference Manual - Page 43
EMS_Exchange - EMS_Move
EMS_OFFSET_ERROR if the offset within the logical
page exceeds the length of the logical page.
EMS_TOO_BIG if a region length exceeds 1M byte.
EMS_UNDEFINED_TYPE if the memory source and
destination types are undefined.
EMS_WRAP_ERROR if an attempt was made to wrap around
the 1M-byte address space of conventional memory
during the move.
EMS_OVERLAP_ERROR if the source and destination
expanded memory regions have the same handle and
overlap.
Parameter: The parameter is a pointer to a an EMSMove structure
as follows:
typedef struct{
unsigned long bytes; Specifies the length of the memory
region to be exchanged or moved.
char stype; Type of memory where the source region
resides. EMS_CONVENTIONAL_MEM
indicates that the source region
resides in conventional memory.
EMS_EXPANDED_MEM indicates that the
source region resides in expanded
memory.
unsigned int shandle; If the source region resides in
expanded memory, shandle specifies the
handle number associated with the
source memory region. If the source
region resides in conventional memory,
shandle has no meaning and should be
set to zero.
unsigned int soffset; Specifies the offset within the source
region from which to do the exchange
or move. If the source region resides
in expanded memory, this offset is
relative to the beginning of the 16K
logical page. If the source region
resides in conventional memory,
soffset specifies the offset, relative
to the beginning of the source
segment, from which to do the exchange
or move.
SCL1 Version 3.1 - Reference Manual - Page 44
EMS_Exchange - EMS_Move
unsigned int sseg; Specifies the initial segment or
logical page number within the source
region from which to do the exchange
or move. If the source region resides
in expanded memory, sseg specifies the
logical page within the source region
from which to do the exchange or move.
If the source region resides in
conventional memory, sseg specifies
the initial segment address within
conventional memory from which to do
the exchange or move.
char dtype; Specifies the type of memory where the
destination region resides.
unsigned int dhandle; If the destination region resides in
expanded memory, dhandle specifies the
handle number associated with the
destination memory region. If the
destination region resides in
conventional memory, dhandle has no
meaning and should be set to zero.
unsigned int doffset; specifies the offset within the
destination region from which to do
the exchange or move. If this region
resides in expanded memory, doffset is
relative to the beginning of the
logical page. If the destination
region resides in conventional memory,
doffset specifies the offset, relative
to the beginning of the destination
segment, to do the exchange or move.
unsigned int dseg; specifies the initial segment or
logical page number within the
destination region from which to do
the exchange or move. If the
destination region resides in expanded
memory then dseg specifies the logical
page within the destination region
from which to do the exchange or move.
If the destination region resides in
conventional memory, dseg specifies
the initial segment address within
conventional memory from which to do
the exchange or move.
}EMSMove;
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 45
EMS_Free
-----------------------------------------------------------------
EMS_Free
-----------------------------------------------------------------
Purpose: Deallocates the logical pages currently allocated to
an EMM handle. Only after the application deallocates
these pages can other applications use them. When a
handle is deallocated, its name is set to all ASCII
nulls (binary zeros). A program must perform this
function before it exits to DOS. If it doesn't, no
other programs can use these pages or the EMM handle.
Prototype: int EMS_Free(int handle);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has deallocated the requested pages
previously allocated.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if the specified EMM handle cannot
be found.
EMS_SAVE_REST_ERROR if the memory manager detected a
save or restore page mapping context error
(EMS_SavePageMap or EMS_RestorePageMap functions);
Parameter: handle - EMM handle. This handle is returned by the
EMS_Alloc function.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 46
EMS_GetAllHandlePages
-----------------------------------------------------------------
EMS_GetAllHandlePages
-----------------------------------------------------------------
Purpose: Returns an array of the open EMM handles and the
number of pages allocated to each one.
Prototype: int EMS_GetAllHandlePages(EMSHandle *p,int *entries);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the array.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameters: The parameter is a pointer to a an EMSHandle
structure as follows:
typedef struct{
unsigned int handle; Contains the value of the open EMM
handle. The values of the handles
this function returns will be in
the range of 0 to 255 decimal
(0000h to 00FFh). The uppermost
byte of the handle is always zero.
unsigned int pages; Contains the number of pages
allocated to the open EMM handle.
}EMSHandle;
Parameter: entries - pointer to an integer value that will be
set to the number of open EMM handles (including the
operating system handle [0]). The number cannot be
zero because the operating system handle is always
active and cannot be deallocated. This number will
not exceed 255.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 47
EMS_GetHandleCount
-----------------------------------------------------------------
EMS_GetHandleCount
-----------------------------------------------------------------
Purpose: Returns the number of open EMM handles (including the
operating system handle 0) in the system.
Prototype: int EMS_GetHandleCount(int *ActiveHandles);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the number of active EMM
handles.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameter: ActiveHandles - pointer to an integer value that will
be set to the number of open EMM handles [including
the operating system handle (0)].This number will not
exceed 255.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 48
EMS_GetHandleName
-----------------------------------------------------------------
EMS_GetHandleName
-----------------------------------------------------------------
Purpose: Gets the eight character name currently assigned to a
handle. There is no restriction on the characters
which may be used in the handle name.
Prototype: int EMS_GetHandleName(int handle,char *name);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the handle name.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if EMS couldn't find the EMM
handle your program specified.
EMS_S_NOT_IMPLEMENTED if an EMS subfunction is
invalid
Parameters:
handle - contains the EMM handle (integer).
name - pointer to an array which will be set to the name
associated with the specified handle.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 49
EMS_GetHandlePages
-----------------------------------------------------------------
EMS_GetHandlePages
-----------------------------------------------------------------
Purpose: Returns the number of pages allocated to a specific
EMM handle.
Prototype: int EMS_GetHandlePages(int Handle,int *Pages);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the number of pages
allocated to the EMM handle.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if EMS couldn't find the EMM
handle your program specified.
Parameters:
Handle - contains the EMM handle (integer).
Pages - pointer to an integer value that will be set to the
number of logical pages allocated to the specified EMM
handle. This number never exceeds 2048 because the memory
manager allows a maximum of 2048 pages (32M bytes) of
expanded memory.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 50
EMS_Init
-----------------------------------------------------------------
EMS_Init
-----------------------------------------------------------------
Purpose: Initialize the Expanded Memory Management functions.
Determine if a valid Expanded Memory Manager (EMS
driver) has been installed in your system.
Prototype: int EMS_Init(void);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has been initialized.
EMS_NOT_IMPLEMENTED if EMS has not been implemented.
Parameters: None
Example:
#include <memory.h>
#include <dos.h>
#include <scl1ems.h>
/* Shows the use of EMS (Expanded memory functions */
void HandleReport(void);
void Pause(void);
void PrintError(unsigned int Error);
char *TestStr[]={
"Data for Page 0",
"Data for Page 1",
"Data for Page 2",
"Data for Page 3",
};
typedef struct{
unsigned int ErrorCode;
char *ErrorMess;
}EMSERRORS;
EMSERRORS emse[]=
{
EMS_NOT_AVAILABLE ,"EMS is not available",
EMS_INTERNAL_ERROR ,"Internal EMM error",
EMS_HARDWARE_ERROR ,"Hardware Error",
EMS_MANAGER_BUSY ,"EMS Manager busy",
EMS_INVALID_HANDLE ,"Invalid handle",
SCL1 Version 3.1 - Reference Manual - Page 51
EMS_Init
EMS_NOT_IMPLEMENTED ,"Function is not implemented",
EMS_NO_MORE_HANDLE ,"No more handles available",
EMS_SAVE_REST_ERROR ,"Save/restore error",
EMS_LOG_GREATER_PH ,"Not enough physical pages",
EMS_LOG_GREATER_AVA ,"Not enough available logical pages",
EMS_ZERO_ALLOC ,"Allocation of 0 pages",
EMS_INVALID_LOG ,"Invalid logical page number",
EMS_INVALID_PH ,"Invalid physical page number",
EMS_STATE_SAVE_FULL ,"Save Stack full",
EMS_SAVE_ALREADY ,"Already saved",
EMS_RESTORE_FAIL ,"Failure restoring",
EMS_S_NOT_IMPLEMENTED ,"Subfunction number not implemented",
EMS_SOURCE_OVERWRITTEN ,"Source overwritten",
EMS_SIZE_ERROR ,"Size error",
EMS_OVERLAP ,"Overlapping regions",
EMS_OFFSET_ERROR ,"Offset error",
EMS_TOO_BIG ,"Size too big",
EMS_OVERLAP_ERROR ,"Overlapping error",
EMS_UNDEFINED_TYPE ,"Undefined memory type",
EMS_DUPLICATE ,"Duplicate handle name",
EMS_WRAP_ERROR ,"Wrap error",
};
EMSMove emove;
char HandleName[9]="SCL1V30";
main()
{
char buffer[80];
int i,handle;
unsigned int ppages,lpages;
void far *p,far *s;
void *t;
printf("\n\nSCL1 Version 3.1 Expanded Memory (EMS) Test\n");
/* Initialize expanded memory manager */
if(EMS_Init() != EMS_OK)
{
/* no EMS available */
printf("No EMS available\n");
exit(-1);
}
SCL1 Version 3.1 - Reference Manual - Page 52
EMS_Init
/* Get EMM version number */
EMS_Version(&i);
memset(buffer,0,sizeof(buffer));
/* use predefined macros to get the major and minor version
number add 0x30 to these values to convert to ASCII, store in
buffer */
buffer[0]=EMS_MAJOR_VER(i) + 0x30;
buffer[1]='.';
buffer[2]=EMS_MINOR_VER(i) + 0x30;
/* print version number */
printf("EMS version: %s\n",buffer);
/* get EMM status and print answer */
printf("EMS status: ");
if((i=EMS_Status())==EMS_OK)
printf("OK\n");
else
PrintError(i);
Pause();
/* get physical pages info */
printf("Physical pages report\n");
/* get total number of physical pages */
EMS_TotalPhPages(&ppages);
printf("\tTotal physical pages: %i\n",ppages);
/* get each physical page address */
for(i=0;i < ppages;++i)
{
EMS_PageAddress(i,&p);
printf("\tPhysical page %i address %X:%X\n",i,FP_SEG(p),
FP_OFF(p));
if(i > 0 && i % 21 == 0)
Pause();
}
Pause();
SCL1 Version 3.1 - Reference Manual - Page 53
EMS_Init
/* get logical pages info */
printf("Logical pages report\n");
/* get total number of logical pages */
EMS_TotalLogPages(&lpages);
printf("\tTotal logical pages: %i\n",lpages);
/* get number of available logical pages */
EMS_AvailableLogPages(&lpages);
printf("\tAvailable logical pages: %i\n",lpages);
Pause();
printf("Allocation/mapping/reallocation Test\n");
if(lpages)
{
/* allocate all available memory */
if((i=EMS_Alloc(&handle,lpages))==EMS_OK)
{
printf("\tSuccesful allocation of %i pages\n",lpages);
if(EMS_SetHandleName(handle,HandleName)==EMS_OK)
{
printf("\tEMS handle has been named %s\n",
HandleName);
if(EMS_GetNamedHandle(HandleName,&i)==EMS_OK)
printf("\tHandle number is %i\n",i);
}
/* print memory handle info */
HandleReport();
for(i=0;i < lpages,i < 4;++i)
{
printf("\tMapping Logical Page %i to Physical Page
%i\n",i,i);
EMS_Map(handle,i,i);
EMS_PageAddress(i,&p);
printf("\tPhysical page %i segment: %X\n",i,
FP_SEG(p));
printf("\tWriting to logical page %i\n",i);
_fmemcpy(p,TestStr[i],sizeof(TestStr[i]));
printf("\tCopying from expanded memory to
conventional memory using EMS_Move\n");
SCL1 Version 3.1 - Reference Manual - Page 54
EMS_Init
/* copy page 0 to our conventional memory buffer */
emove.bytes=sizeof(TestStr[i]);
emove.stype=EMS_EXPANDED_MEM;
emove.shandle=handle;
emove.soffset=0;
emove.sseg=0;
emove.dtype=EMS_CONVENTIONAL_MEM;
emove.dhandle=0;
s=(void far *)buffer;
emove.doffset=FP_OFF(s);
emove.dseg=FP_SEG(s);
EMS_Move(&emove);
/* compare our buffer with page 0 */
if(_fmemcmp(p,(void far *)buffer,sizeof(TestStr[i]))
==0)
printf("\tLogical page %i copied to conventional
memory, compares OK\n",i);
else
printf("\tLogical page %i copied to conventional
memory, error in compare\n",i);
Pause();
}
/* re-allocate to 1 page (16Kb) */
if((i=EMS_Realloc(handle,1))==EMS_OK)
{
printf("\tReallocated to 1 page\n");
/* print memory handle info */
HandleReport();
}
/* free allocated memory */
EMS_Free(handle);
}
else
printf("\tError allocating EMS %x\n",i);
}
}
SCL1 Version 3.1 - Reference Manual - Page 55
EMS_Init
void HandleReport(void)
{
EMSHandle p[255];
char buffer[9];
int i;
/* get number of active handles */
memset(buffer,0,sizeof(buffer));
EMS_GetHandleCount(&i);
printf("\tHandle report\n");
printf("\t\tActive handles: %i\n",i);
/* print the number of memory pages associated with each
handle */
if(EMS_GetAllHandlePages(p,&i)==EMS_OK)
{
while(i--)
{
EMS_GetHandleName(p[i].handle,buffer);
printf("\t\tHandle %s %i, %i pages\n",buffer,p[i].handle,
p[i].pages);
}
}
}
void Pause(void)
{
printf("-- more --");
GetKey();
printf("\r \n");
}
void PrintError(unsigned int Error)
{
int i;
for(i=0;i < sizeof(emse) /sizeof(EMSERRORS);++i)
{
if(emse[i].ErrorCode==Error)
{
printf("\t%s\n",emse[i].ErrorMess);
return;
}
}
printf("\tUnknown error #%X\n",Error);
}
SCL1 Version 3.1 - Reference Manual - Page 56
EMS_Map
-----------------------------------------------------------------
EMS_Map
-----------------------------------------------------------------
Purpose: Maps a logical page at a specific physical page
anywhere in the mappable regions of memory. It can
also unmap physical pages, making them inaccessible
for reading or writing by setting its associated
logical page to FFFFh.
Prototype: int EMS_Map(int handle,int ppage,int lpage);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has mapped the page.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a problem in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if EMS could not find the handle
specified.
EMS_INVALID_LOG if the logical page is out of the
range of logical pages which are allocated to the EMM
handle or if a program attempts to map a logical page
when no logical pages are allocated to the handle.
EMS_INVALID_PH if the physical page number is out of
the range of allowable physical pages.
Parameters:
handle - the EMM handle your program received from a call to
the EMS_Alloc function (integer).
ppage - the number of the physical page into which the
logical page number is to be mapped. Physical pages are
numbered zero-relative (integer).
lpage - the number of the logical page to be mapped at the
physical page within the page frame. Logical pages are
numbered zero-relative (integer).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 57
EMS_MapMultipleEMS
-----------------------------------------------------------------
EMS_MapMultipleEMS
-----------------------------------------------------------------
Purpose: Map (or unmap) logical pages into as many physical
pages as the system supports.
Prototype: int EMS_MapMultipleEMS(int handle,int entries,
EMSMap *parameter);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS the logical pages have been mapped, or
unmapped, at the specified physical pages.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if it couldn't find the specified
EMM handle.
EMS_S_NOT_IMPLEMENTED if an EMS subfunction is
invalid.
EMS_INVALID_LOG if one or more of the mapped pages is
out of the range of logical pages which are allocated
to the EMM handle or if a program attempts to map a
logical page when no logical pages are allocated to
the handle.
EMS_INVALID_PH if one or more of the physical pages
out of the range of mappable physical pages.
Parameters:
handle - the EMM handle your program received from a call to
the EMS_Alloc function (integer).
entries - contains the number of pages to map in the array
(integer).
parameter - pointer to an array of structures of the type
EMSHandle as follows:
SCL1 Version 3.1 - Reference Manual - Page 58
EMS_MapMultipleEMS - EMS_PageAdress
typedef struct{
unsigned int logpage; The number of the logical page to
be mapped from zero to (maximum
number of logical pages allocated
to the handle - 1). If the logical
page number is set to FFFFh, the
physical page is unmapped.
unsigned int phpage; The number of the physical page at
which the logical page is to be
mapped from zero to (maximum number
of physical pages supported in the
system - 1).
}EMSMap;
Example: See EMS_Init
-----------------------------------------------------------------
EMS_PageAdress
-----------------------------------------------------------------
Purpose: Returns the address of a desired physical page
number.
Prototype: int EMS_PageAdress(int page,void far * far * pagept);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has allocated the requested pages to
the assigned EMM handle.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_NO_MORE_HANDLE if all EMM handles are being used.
EMS_LOG_GREATER_PH if there aren't enough expanded
memory pages present in the system to satisfy your
program's request.
EMS_LOG_GREATER_AVA if there aren't enough
unallocated pages to satisfy your program's request.
SCL1 Version 3.1 - Reference Manual - Page 59
EMS_PageAdress - EMS_Realloc
EMS_ZERO_ALLOC if your program attempted to allocate
zero pages.
Parameters:
page - desired physical page number (integer).
pagept - pointer to a pointer that will contain the address
of the desired page number.
Example: See EMS_Init
-----------------------------------------------------------------
EMS_Realloc
-----------------------------------------------------------------
Purpose: Allows an application program to increase or decrease
(reallocate) the number of logical pages allocated to
an EMM handle.
Prototype: int EMS_Realloc(int handle,int pages);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the array.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameters:
handle - the EMM handle your program received from a call to
the EMS_Alloc function (integer).
pages - contains the new size of the allocated memory block
(unsigned integer).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 60
EMS_RestorePageMap
-----------------------------------------------------------------
EMS_RestorePageMap
-----------------------------------------------------------------
Purpose: Restores the page mapping register contents on the
expanded memory boards for a particular EMM handle.
This function lets your program restore the contents
of the mapping registers its EMM handle saved.
Prototype: int EMS_RestorePageMap(int handle);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has restored the state of the page
mapping registers.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if the specified EMM handle cannot
be found.
EMS_RESTORE_FAIL if there is no page mapping register
state in the save area for the specified EMM handle.
Your program didn't save the contents of the page
mapping hardware, so Restore Page can't restore it.
Parameter: handle - the EMM handle your program received from a
call to the EMS_Alloc function (integer).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 61
EMS_SavePageMap
-----------------------------------------------------------------
EMS_SavePageMap
-----------------------------------------------------------------
Purpose: Saves the contents of the page mapping registers on
all expanded memory boards in an internal save area.
The function is typically used to save the memory
mapping context of the EMM handle that was active
when a software or hardware interrupt occurred.
Prototype: int EMS_SavePageMap(int handle);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has saved the state of the page mapping
hardware.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if the specified EMM handle cannot
be found.
EMS_STATE_SAVE_FULL if there is no room in the save
area to store the state of the page mapping
registers. The state of the map registers has not
been saved.
EMS_SAVE_ALREADY if the save area already contains
the page mapping register state for the EMM handle
your program specified.
Parameter: handle - the EMM handle your program received from a
call to the EMS_Alloc function (integer).
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 62
EMS_SetHandleName
-----------------------------------------------------------------
EMS_SetHandleName
-----------------------------------------------------------------
Purpose: Assigns an eight character name to a handle. There is
no restriction on the characters which may be used in
the handle name. The full range of values may be
assigned to each character in a name (that is, 00h
through FFh).
Prototype: int EMS_SetHandleName(int handle,char *name);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has assigned the handle name.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
EMS_INVALID_HANDLE if EMS couldn't find the EMM
handle your program specified.
EMS_S_NOT_IMPLEMENTED if an EMS subfunction is
invalid.
EMS_DUPLICATE if a handle with the specified name
already exists. The specified handle was not
assigned a name.
Parameters:
handle - contains the EMM handle (integer).
name - pointer to an array which contains the name that is to
be assigned to the handle. The handle name must be padded
with nulls if the name is less than eight characters long.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 63
EMS_Status
-----------------------------------------------------------------
EMS_Status
-----------------------------------------------------------------
Purpose: Returns a status code indicating whether the memory
manager is present and the hardware is working
correctly.
Prototype: int EMS_Status(void);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS is present in the system, and the
hardware is working correctly.
EMS_NOT_IMPLEMENTED if EMS has not been implemented.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameters: None
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 64
EMS_TotalLogPages
-----------------------------------------------------------------
EMS_TotalLogPages
-----------------------------------------------------------------
Purpose: Returns the total number of expanded memory pages.
Prototype: int EMS_TotalLogPages(unsigned int *npages);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has returned the number of unallocated
pages and the number of total pages in expanded
memory.
EMS_NOT_IMPLEMENTED if the function code passed to
the manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameter: npages - pointer to an unsigned integer that will
contain the number of expanded memory pages that are
available.
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 65
EMS_Version
-----------------------------------------------------------------
EMS_Version
-----------------------------------------------------------------
Purpose: Returns the version number of the memory manager
software.
Prototype: int EMS_Version(unsigned int *version);
Returns: Returns one of the following messages defined in
header file SCL1EMS.H:
EMS_OK if EMS has been initialized and the hardware
is working correctly.
EMS_NOT_IMPLEMENTED if the function code passed to
the memory manager is not defined.
EMS_INTERNAL_ERROR if a malfunction in the memory
manager software is detected.
EMS_HARDWARE_ERROR if a malfunction in the expanded
memory hardware is detected.
Parameter: version - pointer that will contain the memory
manager's version number in binary coded decimal
(BCD) format. The upper four bits contain the integer
digit of the version number. The lower four bits
contain the fractional digit of version number
(unsigned integer).
Two macros EMS_MAJOR_VER(i) and EMS_MINOR_VER(i) have been
defined int SCL1EMS.H. These macros extract the EMS version
number from the variable version.
To get the most significant part (MAJOR) of the version
number use the following relation:
Major=EMS_MAJOR_VER(i);
The get the least significant part (MINOR) of the version
number use the following relation:
Minor=EMS_MINOR_VER(i);
The EMS driver version number will be:
Version Number = Major.Minor
Example: See EMS_Init
SCL1 Version 3.1 - Reference Manual - Page 66
ErrorBox
-----------------------------------------------------------------
ErrorBox
-----------------------------------------------------------------
Purpose: Displays a box, centered in the screen, with an error
message. Standard error messages have been defined.
You can add your own error messages or modify the
standard messages with the InitUserError function and
your own prompts with the EB_SetUserLang function. To
define the color attributes and a shadow effect use
ErrorShadowOff, ErrorShadowOn and SetErrorBoxColor.
Prototype: void ErrorBox(int ErrNum);
Returns: Nothing.
Parameters: ErrNum - error number corresponding to the error
message to be displayed (integer).
The error numbers defined are:
ERROR DESCRIPTION
2 File not found
3 Path not found
4 Not enough handles
5 Access denied
6 Invalid handle
7 Memory control blocks destroyed
8 Insufficient memory
9 Invalid memory block address
10 Invalid environment
15 Invalid drive
18 No files found
27 Sector not found
29 Write Error
30 Read Error
255 File too Big
-1 DOS Critical Error
Example:
#include <scl1.h>
struct ErrorMess em[]={
256,"Please type either Y for YES\nor N for NO",
0};
main()
{
int Key;
SCL1 Version 3.1 - Reference Manual - Page 67
ErrorBox - ErrorShadowOff - ErrorShadowOn
InitUserError(em);
printf("\nInstall printer driver? (Y/N)\n");
do
{
Key=toupper(getch());
if(Key != 'Y' && Key != 'N')
ErrorBox(256);
else
break;
}while(1);
}
See ErrorShadowOff, ErrorShadowOn, SetErrorBoxColor,
InitUserError and EB_SetUserLang.
-----------------------------------------------------------------
ErrorShadowOff, ErrorShadowOn
-----------------------------------------------------------------
Purpose: Enables or disables a shadow effect when using the
ErrorBox function. Subsequent calls to ErrorBox will
be displayed with (or without) a shadow effect.
Prototype: void ErrorShadowOff(void);
void ErrorShadowOn(void);
Returns: Nothing.
Parameters: None.
Example:
#include <scl1.h>
struct ErrorMess em[]={
1000,"ErrorBox without shadow",
1001,"ErrorBox with shadow",
0};
main()
{
InitUserError(em);
SetShadowColor(8);
ErrorBox(1000);
ErrorShadowOn();
ErrorBox(1001);
ErrorShadowOff();
ErrorBox(1000);
}
See ErrorBox, InitUserError and SetErrorBoxColor.
SCL1 Version 3.1 - Reference Manual - Page 68
FB_SetUserLang - FB3_SetUserLang - WF_SetUserLang
-----------------------------------------------------------------
FB_SetUserLang, FB3_SetUserLang, WF_SetUserLang
-----------------------------------------------------------------
Purpose: Lets you modify the default prompts of the FileBox
and FileBox2 (FB_SetUserLang), FileBox3
(FB3_SetUserLang) or WFileBox (WF_SetUserLang)
functions. With this function you can customize the
default "Load" "Cancel" and "Dir" prompts. This can
useful when writing programs in languages other than
english.
Prototype: void FB_SetUserLang(char **prompt,int offset1,
int offset2);
void FB3_SetUserLang(char **prompt,int offset1,
int offset2);
void FB_SetUserLang(char **prompt,int offset1,
int offset2);
Returns: Nothing.
Parameters:
prompt - pointer to a null terminated array of char pointers
that holds the modified prompts.
offset1 - distance from the right margin (left margin for
WF_SetUserLang) of the box where the first mouse button
("LOAD") will be displayed.
offset2 - distance from the right margin (left margin for
WF_SetUserLang) of the box where the second mouse button
("CANCEL") will be displayed.
Example:
/* this function call sets the FileBox prompts to Spanish */
char *myprompts[]={
"< ACEPTAR >",
"< CANCELAR >",
">>>>",
0,
};
FB_SetUserLang(myprompts,3,3);
SCL1 Version 3.1 - Reference Manual - Page 69
FieldCheck
-----------------------------------------------------------------
FieldCheck
-----------------------------------------------------------------
Purpose: This function is designed to be used with the Fields2
function. When using Fields2 you must specify a
function (in the FData1 structure) to handle events.
It receives messages from Fields2 and must act upon
them returning messages telling whether the cursor
should move to the next or previous field, stay at
the same position or exit the function. This function
can, at the same time, monitor the data that is being
entered and display help or error messages, if
necessary. The FieldCheck function has been designed
to handle the most typical events that are likely to
occur when using Fields2:
TAB - Moves the cursor to the next field.
SHIFT+TAB - Moves the cursor to the previous field.
ESC - Exit Fields2.
ENTER - Its action depends on the active field type.
When LineEditor, TagItem or Select fields are active,
pressing ENTER moves control to the next field. When
ScrollWindow or ListWindow are active, pressing ENTER
will select the highlighted item. When MouseButton is
active, it works as an exit key.
MOUSE EVENTS - Handles all mouse events.
It is recommended that you always use FieldCheck.
Even if you need to define your own field checking
function for data validation or other purposes, you
can still call FieldCheck from your function so that
you don't need to care about the handling of the
events mentioned above.
Prototype: int FieldCheck(FData2 *p);
Returns: The return value is a message. Please refer to the
Fields2 function for details.
Parameters: The required parameter is a pointer to the FData2
structure of the field to be checked.
Example: See Fields2
SCL1 Version 3.1 - Reference Manual - Page 70
Fields
-----------------------------------------------------------------
Fields
-----------------------------------------------------------------
Purpose: This function permits you to make data entry screens.
The fields can accept keyboard input and permit
editing. You can move across the fields using the
TAB, SHIFTTAB keys or your mouse. An exit key is
defined when calling the function. You can define a
data validation and a help function associated with
each field. When you reach each field's end, the
cursor jumps to the next field, thus special field
types (such as date fields) can be defined as
separate fields make them look as one.
Prototype: int Fields(int NColor, int RColor, int NFields,
struct InputFields *ifld, unsigned int ExitKey,
unsigned int HelpKey);
Returns: Returns "1" if a key defined as an exit key is
pressed and "-1" if the ESC key is pressed.
Parameters: The fields information must entered as an array of
structures as follows:
struct InputFields{
int PromptLine; Row position to start the prompt
display.
int PromptCol; Column to start the prompt display.
char *Prompt; Char pointer to the prompt to be
displayed.
int FieldLine; Row to start the field display.
int FieldCol; Column to start the field display.
char *FieldBuffer; Pointer to the buffer to be used to
store the field contents.
int MaxChar; Length of the input field.
int CharType; Mask of valid characters as described
in function CheckChar.
int (* Helpf)(struct InputFields *p);
pointer to a help function. This function receives a
pointer to the fields structure and must be user
supplied.
SCL1 Version 3.1 - Reference Manual - Page 71
Fields
int (* CheckF)(struct InputFields *p);
pointer to a field validation function. This function
receives a pointer to the fields structure and must be
user supplied. It must return a value of "0" if the field
fails the test or a value of "1" to accept the entry.
};
The parameters required are:
NColor - color attributes for the prompt display (int).
RColor - color attributes for the field display (integer).
NFields - number of fields (integer).
InputFields - pointer to the InputFields structure.
ExitKey - key to be used to exit the fields screen (unsigned
integer).
HelpKey - key to be used for calling a help function
(unsigned integer).
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
int test(struct InputFields *p);
int helpf(struct InputFields *p);
char buffer1[29];
char buffer2[29];
char buffer3[29];
char buffer4[29];
char buffer5[13];
char buffer6[11];
char buffer7[11];
char buffer8[11];
char buffer9[9];
char buffer10[11];
struct InputFields data[]={
4,3,"Name:",4,11,buffer1,28,CC_ANY,helpf,test,
6,3,"Address:",6,11,buffer2,28,CC_ANY,helpf,test,
8,3,"City:",8,11,buffer3,28,CC_ANY | CC_CAPITALIZE,helpf,
test,
10,3,"State:",10,11,buffer4,28,CC_LETTER | CC_PUNCTUATION |
CC_CAPITALIZE,helpf,test,
SCL1 Version 3.1 - Reference Manual - Page 72
Fields
12,3,"Zip:",12,11,buffer5,12,CC_DIGIT,helpf,test,
4,44,"Customer Number:",4,60,buffer6,10,CC_DIGIT,helpf,test,
6,44,"Amount Due: $",6,60,buffer7,10,CC_REAL,helpf,test,
8,44,"Credit Limit: $",8,60,buffer8,10,CC_REAL,helpf,test,
10,44,"Date:",10,49,buffer9,8,CC_ANY,helpf,test,
12,44,"Transaction No:",12,60,buffer10,10,CC_DIGIT,helpf,
test};
main()
{
Cls(WHITE_BLACK,CLS_ALL);
Fields(WHITE_BLACK,BLACK_WHITE,10,data,F10,F1);
}
helpf(struct InputFields *p)
/* This function will be called every time the key defined for
help is pressed. It is possible to design a context sensitive
help facility using this feature */
{
PushCursor();
CursorOff();
MessageOn(BLACK_WHITE,"This function will\ndisplay your help
screens.");
WaitTime(200);
MessageOff();
PopCursor();
}
test(struct InputFields *p)
/* This function is called every time you exit a field. It can
make field validation */
{
PushCursor();
MessageOn(BLACK_WHITE,"This function can perform data
validation\neach time the cursor moves out of the
field.");
WaitTime(300);
MessageOff();
PopCursor();
return(1);
}
NOTE: The Fields2 function provides a more flexible way to
perform the same task.
SCL1 Version 3.1 - Reference Manual - Page 73
Fields2
-----------------------------------------------------------------
Fields2
-----------------------------------------------------------------
Purpose: This function lets you integrate various dialog type
functions to design very powerful data entry and
dialog screens. It is similar to Fields but more
flexible. Every field can have its own field check
function which you can create to provide help and
data validation. The screens can contain any of the
following fields:
Line Editor - to enter and edit text and numeric
data.
Scroll Window - to display a window with a list of
items that permits tagging or selecting items.
Mouse Button - a single prompt that permits either to
ignore or activate it.
Tag Item - a field that permits to tag one or various
options.
Select - a field with multiple items for selection.
List Window - similar to the Scroll Window but
permits multiple items in each line.
Calendar - to display a calendar of a given date and
permit the user to modify the date.
User Defined - a field defined by the user.
Prototype: FData2 *Fields2(int Message,FData1 *fd1,FData2 *fd2);
Returns: This function integrates various dialog type
functions. See Appendix "E" for a description of the
general operation of these functions. Returns a
pointer to the FData2 structure.
Parameters: Dialog type functions receive messages and structures
as parameters. The field information is given as an
array of structures type FData1 as follows, one
element for each field:
FData1 structure:
typedef struct{
int FieldType; The type of function for each field
defined in SCL1.H as follows:
SCL1 Version 3.1 - Reference Manual - Page 74
Fields2
LINE_EDITOR, SCROLL_WINDOW, MOUSE_BUTTON,
TAG_ITEM SELECT, LIST_WINDOW, CALENDAR or
USER_DEFINED
void *Structure1; Pointer to a structure that contains all
the information required for the field.
void *Structure2; Pointer to a second structure that
contains the field information. Use "0"
if the field type does not require it.
int (* CheckF)(); Pointer to a function, called every time
an event occurs, that will be responsible
for the program flow. It will constantly
receive messages from Fields2 and return
messages to Fields2 telling it what
should be done. This allows complete
control of the behavior of Fields2, as
well as to perform complex data
validation, context-sensitive help, etc.
SCL1 includes a generic CheckF called
FieldCheck, you should use this function
even if you create your own CheckF. Refer
to FieldCheck for more information.
}FData1;
Fields2 needs a secondary structure type FData2. It is used for
communication between Fields2, CheckF and the calling program.
Each time an event occurs CheckF is called. By reading the FData2
Message element, CheckF knows what has just happened. For
example, the user may have pressed the TAB key to move to the
next field, or he may have clicked the mouse while pointing at
another field, or he may have typed a character. CheckF is
responsible of telling Fields2 what should be done.
Type FData2 structure:
typedef struct{
int Message; Message returned by the active
field.
unsigned int EventInfo; Information about the keys that
have been pressed.
FData1 *Structure; Pointer to the FData1 structure.
int ActiveField; Keeps a record of the current
field, starting with "0" for the
first field. Used internally by the
function.
SCL1 Version 3.1 - Reference Manual - Page 75
Fields2
int FieldsNumber; Holds the number of fields, used
internally by the function.
}FData2;
Type structure FData3:
typedef struct{
int EventInfo; Information about the last illegal
or exit key that was pressed.
int (* UserField)(); Pointer to the function that will
handle user defined fieldtype.
}FData3;
NOTE: The information stored in structure type FData3 is used to
define the parameters for user defined fields, please refer to
the sample user defined function after the Fields2 example.
Messages:
The messages that can be sent to the Fields2 function are:
F_INIT - initialize the FData2 structure.
F_DRAW - draw the Fields2 screen.
F_ACTIVE - edit the Fields2 information.
F_DRAW_NR - draw the Fields2 display and do not reset the
field values. With the F_DRAW message, Fields2 resets all the
fields to their starting position.
F_COLORS - dialog functions get the colors from their
structures. If you have initialized these structures as
static data you can change the colors by sending this message
to Fields2. It will change the colors in each structure to
those specified as additional parameters. The first value
passed is the Normal and the second is the Reversed Color.
F_ALLOC - after this message is sent, when Fields2 finds a
LineEditor type field, it will automatically allocate memory
for the buffer.
F_FREE - when this message is sent Fields2 will free all
buffers allocated for LineEditor type fields. It is
recommended that either allocate all buffers using F_ALLOC or
manually but not both. When this message is sent it will
clear all buffers, so be careful.
SCL1 Version 3.1 - Reference Manual - Page 76
Fields2
When the CheckF is called, after determining what should be done,
it can send one the following messages back to Fields2:
F_MOUSE_EVENT - When the mouse is clicked outside the active
field FieldCheck will receive a LE_MOUSE_EVENT (SW_ or LW_
etc.) and FieldCheck should return a F_MOUSE_EVENT message to
Fields2. Fields2 will then give control to the field (if any)
that can handle the mouse event.
F_POSITION_STAY - instructs Fields2 not to move to other
field. It is useful when the field does not pass the
validation check, to permit the user to edit its contents.
F_POSITION_UP - move to the next field.
F_POSITION_DOWN - move to the previous field.
F_SET_POSITION - move the cursor to a desired field. You must
first set the ActiveField structure member to the desired
field number and then return this message.
F_EXIT - instructs Fields2 to exit.
F_SET_POS_EXIT - exit after setting a predetermined position.
F_CHECK_ALL - when a CheckF senses an exit condition, it
sends this message to Fields2 who will call any CheckF
defined for each field. By returning this message you can be
sure that the data in each field is valid, since Fields2 will
move to any field that do not pass the CheckF validation. If
all Fields are valid it will behave as an F_EXIT message.
F_FIELDSTART - when the cursor is located in one valid field
this message will be sent to the FieldCheck function.
F_START - This message is sent to the FieldCheck function (in
the FData2 Message element) when Fields2 first receives the
F_ACTIVE message. You can use this message to initialize or
modify any condition before the user gets control.
Due to the function integrating purpose of Fields2, it does not
return messages.
SCL1 Version 3.1 - Reference Manual - Page 77
Fields2
Example:
#include <string.h>
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
/* Shows the use of the Fields2 and FieldCheck functions and how
to create an user defined field check function.
The data entry field has a Select type field, one LineEditor
and two mouse buttons.
The field check function will:
1) Check for F1 key to display context sensitive help.
2) Check if user has selected YES or NO. The LineEditor
field color is grayed in the case of NO.
3) Keep the cursor off the LineEditor field if the user
has selected NO and the LineEditor field is grayed
out.
4) Check before exit if cancel is not selected and YES
has been selected if the user has fill out the
LineEditor field. */
int OurFieldCheck(FData2 *fd2); /* our CheckF prototype */
int Color1=WHITE_BLUE; /* Colors are initialized */
int Color2=BLACK_CYAN; /* for a color monitor */
int Color3=BROWN_BLACK+HIGHLIGHT;
/* Our first field will be a Select type */
SData1 sd1[]={ /* This is Select's first structure */
11,37,"YES",
11,47,"NO",
0};
/* Select's secondary structure: */
SData2 sd2={23,11,16,"Create backup files:",0,0,0,0};
/* Our second field will be a LineEditor type. This structure
defines the LineEditor configuration */
LEData led={23,13,16,"Backup Directory:",112,13,34,30,30,
CC_PATH+CC_CAPITALIZE, 0,0,0,0,0,0,2,1,0,0,0,0,0,0,0};
SCL1 Version 3.1 - Reference Manual - Page 78
Fields2
/* The next two fields will be of the MouseButton type. */
MBData mb1={23,112,15,28,15,33,15,28,"≡ OK ≡",0,0,0,0};
MBData mb2={23,112,15,42,15,51,15,42,"≡ CANCEL ≡",0,0,0,0};
FData1 fd1[]={ /* This is the FData1 structure: */
SELECT,sd1,&sd2,OurFieldCheck,
LINE_EDITOR,&led,0,OurFieldCheck,
MOUSE_BUTTON,&mb1,0,OurFieldCheck,
MOUSE_BUTTON,&mb2,0,OurFieldCheck,
0};
char F1Text[]=" Press F1 for Help ";
main()
{
FData2 fd2; /* Fields2 secondary structure */
if(Video()==MONO) /* Verify the type of display and change */
{ /* colors if necessary */
Color1=WHITE_BLACK;
Color2=BLACK_WHITE;
Color3=BLACK_WHITE+HIGHLIGHT;
}
/* Clear the screen and draw a box */
Cls(Color1,10,13,16,66);
Box(Color1,0,10,13,16,66);
WriteScreen(Color1,16,Center(F1Text),F1Text);
/* Call Fields2 with a F_INIT message */
Fields2(F_INIT,fd1,&fd2);
/* allocate buffer for LineEditor field */
Fields2(F_ALLOC,fd1,&fd2);
/* Tell Fields2 to modify colors to new values */
Fields2(F_COLORS,fd1,&fd2,Color1,Color2);
/* Draw fields */
Fields2(F_DRAW,fd1,&fd2);
InitMouse(IM_SHOW);
SCL1 Version 3.1 - Reference Manual - Page 79
Fields2
/* Activate, now our CheckF will be in control of program flow */
Fields2(F_ACTIVE,fd1,&fd2);
/* Check the FData2 structure to see if the user presses ESCAPE
or selects the CANCEL mouse button for exiting */
if(fd2.ActiveField==3 || fd2.EventInfo==ESC)
exit(-1); /* CANCEL selected */
else
exit(0); /* OK selected */
}
/* This is the custom field check function */
int OurFieldCheck(FData2 *fd2)
{
int Mess;
/* Let SCL1 FieldCheck function do most of the work */
Mess=FieldCheck(fd2);
/* 1) We will watch the F1 help key. It will be reported by
Fields2 with an ILLEGAL_KEY message in the FData2
EventInfo structure element.*/
if(fd2->Message == LE_ILLEGAL_KEY && fd2->EventInfo==F1)
{
/* display help, fd2->ActiveField = active field number */
Help(fd2->ActiveField);
/* return POSITION_STAY message so that the cursor is not
moved to another field */
Mess=F_POSITION_STAY;
}
/* 2) Check if the Select field is active and if a
S_NEW_POSITION message, was send by Select. This message
is received each time the user changes his selection.
We'll check current position to validate or invalidate
the LineEditor field */
else if(fd2->ActiveField==0 && fd2->Message==S_NEW_POSITION)
{
if(sd2.Position==0) /* YES selected */
SCL1 Version 3.1 - Reference Manual - Page 80
Fields2
{
led.PColor=Color1;
led.FColor=Color2; /* normal colors */
}
else
/* NO selected, use gray color */
{
led.PColor=BLACK_BLUE + HIGHLIGHT;
led.FColor=BLACK_BLACK + HIGHLIGHT;
}
LineEditor(LE_DRAW,&led); /* redraw LineEditor */
}
/* 3) The FIELDSTART message is send each time a new field
receives control. We'll check this message and if the
LineEditor field is active we'll check its color. If it
is set to gray color it means that the user has selected
not to create backup files. In this case we'll move to
the next or previous field. By checking fd2->EventInfo
we'll know if the user had previously pressed TAB (for
the next field) or SHIFT+TAB */
else if(fd2->ActiveField==1 && fd2->Message==F_FIELDSTART)
{
if(led.FColor==BLACK_BLACK + HIGHLIGHT)
{
if(fd2->EventInfo==TAB)
fd2->ActiveField=2; /* next field */
else
fd2->ActiveField=0; /* previous field */
Mess=F_SET_POSITION;
}
}
/* 4) When the user wants to exit we'll check if a string has
been entered in the LineEditor field if Select is set to
YES and the OK mouse button was selected. We know we are
about to exit fields when FieldCheck returns and F_EXIT
message. We'll also check if the key that was used to
exit was ESCAPE or the CANCEL button was selected, in
these cases the user has selected to cancel the
operation. */
else if(Mess==F_EXIT && fd2->EventInfo != ESC && fd2->ActiveField
!= 3)
{
SCL1 Version 3.1 - Reference Manual - Page 81
Fields2
/* if Select is in YES position and no directory has been
entered */
if(sd2.Position==0 && strlen(led.Buffer)==0)
{
/* display error, change message to POSITION_STAY and
move the cursor to the LineEditor field */
MessageOn(Color3,"Directory must be entered!");
Mess=F_POSITION_STAY;
fd2->ActiveField=1;
WaitKeyMouse();
MessageOff();
}
}
/* Mess holds the message Fields2 will receive, a POSITION_STAY
message or the message returned by FieldCheck */
return(Mess);
}
char AllHelp[]=" TAB-next SHIFT TAB-previous ";
Help(int field)
{
/* save cursor status and turn it off */
PushCursor();
CursorOff();
/* field tells us the field number that is active, we will use
it to display context sensitive help */
switch(field)
{
case 0: /* first field */
MessageOn(Color3,"Use arrow keys to select if you\nwant
to create backup files.");
break;
case 1: /* second field */
MessageOn(Color3,"Type Backup files directory.");
break;
SCL1 Version 3.1 - Reference Manual - Page 82
Fields2
case 2: /* third field */
MessageOn(Color3,"Press ENTER to validate\nyour
selection.");
break;
case 3: /* fourth field */
MessageOn(Color3,"Press ENTER or ESC to\ncancel your
selection.");
break;
}
WriteScreen(Color3,12,Center(AllHelp),AllHelp);
/* wait for mouse or keystroke, remove message, restore cursor */
WaitKeyMouse();
MessageOff();
PopCursor();
}
/****************************************************************
This example shows how to create an user defined field type
to use with the Fields2 function.
We will create a field that displays one of several
predefined strings. The user can select one by using the UP
and DOWN arrow keys or by clicking the mouse after pointing
at any of the two small arrows. To create an user defined
field we need to create the function that will handle the new
field type. This function must be written with the following
requirements:
1) The function must be capable of receiving and handling
the following messages:
Message Action
RESET - Reset all internal variables to start-up
conditions.
DRAW - Draw the field to the screen.
ACTIVE - Get user input.
CHECK_MOUSE - Check if a mouse event has occurred
inside the field area.
SCL1 Version 3.1 - Reference Manual - Page 83
Fields2
2) The function must return the following messages to
Fields2:
Message Action
OK - Action requested was successfully
performed.
EXIT_KEY - A key defined as an exit key was pressed.
ILLEGAL_KEY - An unknown key was pressed.
MOUSE_EVENT - A mouse event not related to this
function has occurred.
MY_MOUSE - A CHECK_MOUSE message is answered with
this message if the mouse event is
related to this function. Fields will
give control to this function when a
MY_MOUSE event is returned.
NEW_POSITION - the user has moved to a new position or
selected a new element. (This one is not
required but it is highly recommended).
3) All local data (color, position, etc.) must be stored in
a structure. A pointer to this structure will be passed
as a parameter whenever the function is called. Look at
any SCL1 dialog function for an example. The use of a
structure to hold local data makes possible for a single
LineEditor structure to handle all LineEditor fields in a
data-entry screen.
4) The following parameters are passed each time the
function is called:
Message (int) any of the messages described above.
st (void *) pointer to the field related structure.
fd3 (FData3 *) pointer to a FData3 structure that has
the following format:
typedef struct{
int EventInfo;
int (* cdecl UserField)();
}FData3;
5) When called the function must:
SCL1 Version 3.1 - Reference Manual - Page 84
Fields2
a) Service the message received.
b) If an illegal or exit key is detected it should copy
the key's SCAN/ASCII code to the EventInfo element of
the FData3 struct.
c) Return the correct message.
Before calling Fields2 you must properly initialize the user
defined and the FData3 structure. In the case of FData3 only
the UserField element needs to be initialized (points to the
function that will handle the user defined field type).
****************************************************************/
#include <scl1.h>
#include <scl1keys.h>
/* function prototype of our new field handler */
int SelectString(int Message,void *st,FData3 *fd3);
/* new field data */
char *MyText[]={
"111111111111111111",
"222222222222222222",
"333333333333333333",
0,
};
typedef struct{ /* our new field structure */
int Color;
int Row;
int Col;
int Position;
int Items;
int Length;
char **Text;
}SSData;
/* initialize our field structure */
SSData ssd={7,7,13,0,3,0,MyText};
/* a mouse button structure */
MBData mb={7,112,9,13,9,18,9,13,"< OK >",0,0,0,0};
SCL1 Version 3.1 - Reference Manual - Page 85
Fields2
/* It is very important to initialize our FData3 structure so
that the UserField element points to the function that
handles the new field type */
FData3 ssfd3={0,SelectString};
/* FData1 struct */
FData1 fd1[]={
/* First field is our used defined field, the SSData pointer
is used as Structure1 element and the FData3 pointer as
Structure2 element.
We will use SCL1's default FieldCheck function */
USER_DEFINED,&ssd,&ssfd3,FieldCheck,
MOUSE_BUTTON,&mb,0,FieldCheck,
0};
main()
{
FData2 fd2;
Cls(7,CLS_ALL); /* Clear screen */
InitMouse(IM_SHOW); /* initialize mouse */
Fields2(F_INIT,fd1,&fd2); /* init fields */
Fields2(F_DRAW,fd1,&fd2); /* draw */
Fields2(F_ACTIVE,fd1,&fd2); /* give control */
}
/* our new field type. Here we'll send received messages for
processing */
int SelectString(int Message,void *st,FData3 *fd3)
{
SSData *ssd;
ssd=(SSData *)st;
/* You could define any messages for your field, but the
value assigned to each message must equal those assigned
to regular dialog functions. In this example we will use
LineEditor messages */
switch(Message)
{
case LE_DRAW:
DrawUF(ssd);
return(LE_OK);
SCL1 Version 3.1 - Reference Manual - Page 86
Fields2
case LE_ACTIVE:
return(ActiveUF(ssd,fd3));
case LE_CHECK_MOUSE:
return(CheckUFMouse(ssd,fd3));
case LE_RESET:
ssd->Position=0; /* reset position to 0 */
return(LE_OK);
}
return(LE_OK);
}
/* Draws our field to the screen and initializes several
elements of our structure */
int DrawUF(SSData *ssd)
{
int i=0,j,maxlength=0;
while(ssd->Text[i] != 0) /* count the number of items */
{
j=strlen(ssd->Text[i]); /* save the largest element size */
if(j > maxlength)
maxlength=j;
++i;
}
ssd->Items=i; /* save in struct */
ssd->Length=maxlength;
/* write string */
WriteScreenLen(ssd->Color,ssd->Row,ssd->Col+2,maxlength,ssd->Text
[ssd->Position]);
/* draw up and down arrows */
WriteChar(ssd->Color,ssd->Row,ssd->Col,1,24);
WriteChar(ssd->Color,ssd->Row,ssd->Col+maxlength+3,1,25);
}
/* This functions is called when our field is active */
ActiveUF(SSData *ssd,FData3 *fd3)
{
unsigned int key;
SetCurPos(ssd->Row,ssd->Col+2); /* position cursor */
do
{
if(MSE_LPress) /* mouse event? */
{
SCL1 Version 3.1 - Reference Manual - Page 87
Fields2
if(CheckUFMouse(ssd)==LE_MY_MOUSE) /* our mouse? */
{ /* clicked at the up arrow key */
if(MSE_LpX==ssd->Col)
{
WaitTime(25);
goto UpKey;
}
/* clicked at the down arrow key */
else if(MSE_LpX==ssd->Col+ssd->Length+3)
{
WaitTime(25);
goto DownKey;
}
}
else
/* clicked outside our area, return a
MOUSE_EVENT message */
return(LE_MOUSE_EVENT);
}
if(KeyReady()) /* check keystrokes */
{
key=GetKey();
switch(key)
{
case UP:
UpKey:
if(ssd->Position > 0)
--ssd->Position; /* change position */
else
ssd->Position=ssd->Items-1;
DrawUF(ssd); /* update screen */
return(LE_NEW_POSITION);
case DOWN:
DownKey:
if(ssd->Position + 1 < ssd->Items)
++ssd->Position; /* change position */
else
ssd->Position=0;
DrawUF(ssd); /* update screen */
return(LE_NEW_POSITION);
case TAB:
case SHIFTTAB: /* handle exit keys */
SCL1 Version 3.1 - Reference Manual - Page 88
Fields2
case ESC:
fd3->EventInfo=key; /* save key value */
return(LE_EXIT_KEY);
default: /* handle unknown keys */
fd3->EventInfo=key; /* save key value */
return(LE_ILLEGAL_KEY);
}
}
}while(1);
}
/* This function checks if the mouse has been clicked in our
area */
CheckUFMouse(SSData *ssd)
{
if(MSE_LpY==ssd->Row && MSE_LpX >= ssd->Col && MSE_LpX <=
ssd->Col+ssd->Length+3)
/* return MY_MOUSE if YES */
return(LE_MY_MOUSE);
else
return(LE_MOUSE_EVENT);
}
SCL1 Version 3.1 - Reference Manual - Page 89
FileBox
-----------------------------------------------------------------
FileBox
-----------------------------------------------------------------
Purpose: Displays a box with the directory information for
loading or selecting files with the keyboard or
mouse. Fills a buffer with the selected file/path.
You can change the MouseButton and prompt text with
the FB_SetUserLang function.
Prototype: int FileBox(int NColor, int RColor,char *Buffer);
Returns: Returns "-1" if the operation is canceled by the user
by pressing ESC or selecting the cancel option, or
"0" if there are no problems.
Parameters:
NColor - color attributes for normal color display (int).
RColor - color attributes for reverse color display (int).
Buffer - char pointer to the buffer that will hold the
selected filename. The search string is placed in the buffer
before calling the function. If an empty buffer is used (NO
SEARCH STRING SPECIFIED), the function will place the default
path and the "*.*" search string into it. This buffer must be
of size FB_BUF_SIZE as defined in SCL1.H.
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=BLACK_WHITE;
int Color2=WHITE_BLACK;
char FileBuf[FB_BUF_SIZE]; /* Buffer big enough so that the
directory information will fit */
main()
{
FileBox(Color1,Color2,FileBuf);
WriteScreen(Color1,20,12,"You have Selected:");
WriteScreen(Color1,20,33,FileBuf);
}
See also FileBox2, FileBox3 and WfileBox.
SCL1 Version 3.1 - Reference Manual - Page 90
FileBox2 - FileBox3 - WFileBox
-----------------------------------------------------------------
FileBox2, FileBox3, WFileBox
-----------------------------------------------------------------
Purpose: FileBox2 displays a box with for selecting files
using the keyboard or mouse. Fills a buffer with the
selected file/path. Displays the action MouseButtons
at the right of the box. You can change the
MouseButton and prompt text with the FB_SetUserLang
function. FileBox3 can also display the file's size,
date, time and attributes. Files can be sorted by
name, extension, size, date, time or attribute. You
can change the prompts and MouseButton text using the
FB3_SetUserLang function. WFileBox is similar to
FileBox2 but uses a full screen. You can use
WF_SetUserLang to change the Mouse Button prompts.
Prototype: int FileBox2(int Message, FBData *p)
int FileBox3(int Message, FB3Data *fb3)
int WFileBox(int Message, FBData *p)
Returns: This is a dialog derived function. See Appendix "E"
for a description of the general operation of these
functions. Returns the messages described in the
Messages section.
Parameters: The file box information is given in a structure type
FBData (for FileBox2 and WFileBox) or FB3Data (for
FileBox3) as follows:
Structure type FBData; (Used with FileBox2 and WFileBox)
typedef struct{
int NColor; Normal color for the file box display.
int RColor; Reversed color for the file box display.
int UpperRow; Upper row position for the file box.
int LeftCol; Left column position for the file box.
int LowerRow; Lower row position for the file box.
int RightCol; Right column position for the file box.
SCL1 Version 3.1 - Reference Manual - Page 91
FileBox2 - FileBox3 - WFileBox
char *Filename; Char pointer to the buffer that will hold
the selected filename. The search string
is placed in the buffer before calling
the function. If an empty buffer is used,
the function will place the default path
and the "*.*" search string in the
buffer. It must be of size FB_BUF_SIZE as
defined in SCL1.H.
int Attrib; File attributes as defined by the DOS.
Refer to Appendix "A" for more details.
}FBData;
Structure type FB3Data;
typedef struct{
int NColor; See description for FBData structure above.
int RColor; " "
int UpperRow; " "
int LeftCol; " "
int LowerRow; " "
int RightCol; " "
char *Filename; " "
int Attrib; " "
unsigned int Display; Variable used to specify what to show
in the FileBox display. The following
constants can be used in this
specification:
FB_NAME - show name.
FB_SIZE - show size.
FB_DATE - show date.
FB_TIME - show time.
FB_ATTRIB - show attributes.
FB_DMY - show date using the Day-
Month-Year format.
FB_YMD - show date using the Year-
Month-Day format.
They can be concatenated (added) to
specify various options,as in:
FB_NAME + FB_SIZE + FB_DATE + FB_TIME
+ FB_ATTRIB
unsigned int SortType; Variable used to define the desired
sorting order of the files. The
following constants can used in this
specification:
SCL1 Version 3.1 - Reference Manual - Page 92
FileBox2 - FileBox3 - WFileBox
FB_NAME - sort by name
FB_EXT - sort by extension
FB_DATE - sort by date
FB_ATTRIB - sort by attribute
The following constants can be used to
specify the sorting action:
FB_REVERSE - sort in reverse order
FB_DIR_FIRST - place the directories
before the files.
int FileNumber; Number of files found.
int DirNumber; Number of directories found.
}FB3Data;
Messages:
The following messages can be sent to FileBox2, FileBox3 and
WFileBox:
FB_INIT - initialize the FBData or FB3Data structure to NULL
and set the following default values:
NColor - set to white characters in a black background or
the normal color set by SetDialogColors.
RColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
UpperRow, LeftCol, LowerRow and RightCol - set to display
the FileBox centered in the screen.
Attrib - files and sub-directories.
For FB3Data only;
Display - set to show the file name, size, date, time and
attributes. The date is displayed in the Month-Day-Year
format.
SortType - set to sort the files by name.
FB_DRAW - draw the FileBox to the screen.
FB_ACTIVE - browse through the displayed filenames and permit
a selection or to cancel the operation using the cursor
movement keys as follows:
SCL1 Version 3.1 - Reference Manual - Page 93
FileBox2 - FileBox3 - WFileBox
Key Action
Up Arrow one item up.
Down Arrow one item down.
END end of file list.
HOME beginning of list.
Page Up one screen up.
Page Down one screen down.
FB_RESET - when this message is sent the filebox variables
are reset to the default value.
The following messages can be returned by FileBox2, FileBox3 and
WFileBox:
FB_OK - the action requested has been performed and a file
has been selected.
FB_CANCEL - the operation has been canceled.
For FileBox3 only;
FB_NO_MEM - there is not enough memory left to perform the
requested action.
FB_ILLEGAL_OP - you have specified an illegal option.
Example:
#include <scl1.h>
#include <scl1clor.H>
/* Shows the use of filebox functions */
main()
{
char Buffer[FB_BUF_SIZE];
FBData fb2;
FB3Data fb3;
FBData fbw;
memset(Buffer,0,sizeof(Buffer));
InitMouse(IM_SHOW);
FileBox2(FB_INIT,&fb2); /* initialize the FBData structure */
WFileBox(FB_INIT,&fbw); /* initialize the FBData structure */
FileBox3(FB_INIT,&fb3); /* initialize the FB3Data structure */
SCL1 Version 3.1 - Reference Manual - Page 94
FileBox2 - FileBox3 - WFileBox
fb2.NColor=fb3.NColor=fbw.NColor=WHITE_BLACK;/* change display
colors */
fb2.RColor=fb3.RColor=fbw.RColor= BLACK_WHITE;
fb2.Filename=fb3.Filename=fbw.Filename=Buffer; /* buffer to hold
dir info */
/* set files attributes */
fb2.Attrib=fb3.Attrib=fbw.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+
F_DIRECTORY;
FileBox2(FB_DRAW,&fb2); /* display FileBox */
FileBox2(FB_ACTIVE,&fb2); /* let user make a selection */
/* sort by name and place directories first in the list */
fb3.SortType=FB_NAME+FB_DIR_FIRST;
FileBox3(FB_DRAW,&fb3); /* display FileBox */
FileBox3(FB_ACTIVE,&fb3); /* let user make a selection */
WFileBox(FB_DRAW,&fbw); /* display Wide FileBox */
WFileBox(FB_ACTIVE,&fbw); /* let user make a selection */
}
SCL1 Version 3.1 - Reference Manual - Page 95
File2Buf - HFile2Buf
-----------------------------------------------------------------
File2Buf, HFile2Buf
-----------------------------------------------------------------
Purpose: Reads a file into a buffer. With HFile2Buf the file
size can be larger than 64K, using the compact and
large models. HFile2Buf's prototype is declared in
SCL1HUGE.H
Prototype: int File2Buf(char* Filename, char* Buffer,
unsigned int* MaxSize);
int HFile2Buf(char *Filename,char huge *Buffer,
unsigned long *MaxSize);
Returns: Returns "0" when no errors occur. When errors occur
it returns "-1" to indicate a critical DOS error,
"255" to indicate that the file is larger than the
size specified with MaxSize, or the standard DOS
error code for other errors. You must have called
TrapInt24 before in order to trap critical errors.
The number of bytes read are stored in MaxSize.
Parameters:
Filename - valid pathname of the file to be read (char).
Buffer - buffer to hold the information (char pointer for
File2Buf and huge file pointer for Hfile2Buf).
MaxSize - number of bytes to read (unsigned integer for
File2Buf and unsigned long for Hfile2Buf).
Example: See Buf2Disk
See also Buf2Disk, HBuf2Disk and TrapInt24.
SCL1 Version 3.1 - Reference Manual - Page 96
FillBlock
-----------------------------------------------------------------
FillBlock
-----------------------------------------------------------------
Purpose: Fills a screen area, defined with the parameters
passed to the function, with a given character.
Prototype: void FillBlock(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol,int Character);
Returns: Nothing
Parameters:
Color - color attribute for the display (integer).
UpperRow - upper row position of the display area (integer).
LeftCol - left column position of the display area (integer).
LowerRow - lower row position of the display area (integer).
RightCol - right column position of the display area
(integer).
Character - character to be used for filling the screen area.
This can be any valid character (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=BLACK_WHITE;
main()
{
FillBlock(Color1,2,2,20,40,178);
/* Will fill the area between rows 2-10 and columns 20-40 with
character 178. */
}
SCL1 Version 3.1 - Reference Manual - Page 97
FindFirst - FindNext
-----------------------------------------------------------------
FindFirst, FindNext
-----------------------------------------------------------------
Purpose: Searches a disk directory for the file that matches
the specified search attributes using DOS system call
0x4e. After finding the first matching file you must
use FindNext to get subsequent matching files.
Prototype: int FindFirst(char *SearchString,struct FileData
*Buffer, int SearchAtr);
int FindNext(void);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
DOS error code "18" is returned when no more files
are found.
Parameters:
SearchString - pointer to a string with the search mask to be
used (for example C:\BIN\*.EXE). If a matching file is found
the FileData structure is filled with the file information.
FileData - pointer to a structure of type FileData defined in
SCL1.H:
struct FileData{
char reserved[21]; Is an area reserved by DOS for
subsequent calls to FindNext.
char attrib; Identifies the type of file found. Can
be one or more of the following
constants defined in SCL1.H: (use an
OR operation to add them)
F_READ_ONLY, F_HIDDEN, F_SYSTEM,
F_VOLUME, F_DIRECTORY, F_ARCHIVE
struct FILETIME time; Structure with bit-fields members that
holds the time when the file was
created or last updated. FILETIME
structure is defined in SCL1.H:
struct FILETIME{
unsigned int seconds:5; Value from "0" to "59".
unsigned int minutes:6; Value from "0" to "59".
unsigned int hours:5; Value from "0" to "24".
};
SCL1 Version 3.1 - Reference Manual - Page 98
FindFirst - FindNext
struct FILEDATE date; structure with bit-fields members
that holds the date when the file
was created or last updated.
FILEDATE structure is defined in
SCL1.H:
struct FILEDATE{
unsigned int day:5; Value from "1" to "31".
unsigned int month:4; Value from "1" to "12".
unsigned int year:7; value from "0" to "119", to
get the real year add "80" to
this value.
};
long size; File's size in bytes.
char name[13]; File's name.
};
SearchAtr - is the DOS file attribute of eligible files
(files that will be reported). The following attribute
constants have been defined in SCL1.H:
F_ARCHIVE only archive files.
F_DIRECTORY archive and directories.
F_READ_ONLY archive and read-only files.
F_HIDDEN archive and hidden files.
F_SYSTEM archive and system files.
F_VOLUME ONLY the volume label is reported.
Note: This functions sets the DTA (Disk Transfer Area) to point
to the FileData structure. Is important that you do not
modify the DTA between a call to FindFirst and FindNext.
The DTA must be declared as static data.
Example:
#include <scl1.h>
/* Shows the use of FindFirst/Next to get a directory list */
#define NO_MORE_FILES 18
static void printinfo(struct FileData *fd);
struct FileData fd; /* file info will be stored here */
main()
{
int RetVal;
SCL1 Version 3.1 - Reference Manual - Page 99
FindFirst - FindNext
RetVal=FindFirst("*.*",&fd,F_VOLUME); /* read volume label */
if(RetVal==NO_MORE_FILES) /* no more files? */
printf("\nVolume has no label\n\n");
else
printf("\nVolume label: %s\n\n",fd.name);
/* read other files. Subdirectories, hidden, system and
archive files */
RetVal=FindFirst("*.*",&fd,F_DIRECTORY | F_SYSTEM | F_HIDDEN);
/* Get filenames while no error is reported */
while(RetVal==0)
{
printinfo(&fd); /* print file information */
RetVal=FindNext(); /* get next file */
}
}
static void printinfo(struct FileData *fd)
{
printf("%-13s",fd->name); /* print file name */
/* if file is not a directory, print file size */
if(fd->attrib == F_DIRECTORY)
printf(" <DIR>");
else
printf("%7li",fd->size);
/* print date and time */
printf(" %.2i-%.2i-%.2i %.2i:%.2i:%.2i\n",fd->date.month,
fd->date.day,fd->date.year+80,fd->time.hours,
fd->time.minutes, fd->time.seconds);
SCL1 Version 3.1 - Reference Manual - Page 100
GetCharSet - GetCharSetAddress
-----------------------------------------------------------------
GetCharSet
-----------------------------------------------------------------
Purpose: Copies one or more character definitions from the
active character definition table in use by the BIOS
to an user defined buffer. Each character is defined
in an 8 bits rows by 32 lines matrix. Each screen
scan line is represented by one byte (8 bits). VGA
monitors normally use the first 16 bytes, EGA 14 and
CGA 8, but the BIOS uses 32 bytes tables for each
character. This function can be used before you call
the ModifyCharSet function to modify characters so
that you can restore them to the original values.
See Appendix "J".
Prototype: void GetCharSet(int StartCode,int TotalChars,
char *Buffer);
Returns: Nothing
Parameters:
StartCode - ASCII code of the first character to store
(integer).
TotalChars - number of characters to store (integer).
Buffer - pointer to a buffer that will contain a bitmap of
the stored characters. The buffer size needs to be equal to
the number of characters * 32.
Example: See ModifyCharSet
-----------------------------------------------------------------
GetCharSetAddress
-----------------------------------------------------------------
Purpose: Gets the ROM character tables address. You must
specify which character table you desire using one of
the constants defined in SCL1.H (GCA_8X8A, GCA_8X8B,
GCA_8X14, GCA_8X16). Refer to Appendix "J".
Prototype: char far * GetCharSetAddress(int table);
Returns: Far pointer to one of the BIOS character definition
tables stored in ROM.
Parameters: Table - character table number (integer).
SCL1 Version 3.1 - Reference Manual - Page 101
GetCurCol - GetCurLine - GetCurrentDir
-----------------------------------------------------------------
GetCurCol, GetCurLine
-----------------------------------------------------------------
Purpose: Returns the current cursor position.
Prototype: int GetCurCol(void);
int GetCurLine(void);
Returns: GetCurCol returns the column position and GetCurLine
returns the row position.
Parameters: None
Example: See PopCursor
-----------------------------------------------------------------
GetCurrentDir
-----------------------------------------------------------------
Purpose: Returns a string holding the default drive and path.
Prototype: int GetCurrentDir(char *PathBuffer);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: PathBuffer - pointer to a buffer to hold the pathname
and drive letter (char).
Example:
#include <scl1.h>
main()
{
int i,char buffer[160];
i=GetCurrentDir(buffer);
if(i)
printf("\nDOS reports error #%i\n",i);
else
printf("\nCurrent directory is %s\n",buffer);
}
SCL1 Version 3.1 - Reference Manual - Page 102
GetCurSize
-----------------------------------------------------------------
GetCurSize
-----------------------------------------------------------------
Purpose: Saves the current cursor size in variable
GCS_CursorSize and returns the current cursor size.
Prototype: int GetCurSize(void);
Returns: The current cursor size.
Parameters: None
Example:
#include <scl1.h>
main()
{
int i;
i=GetCurSize();
printf("\nCursor size has been saved in local variable, hit any
key...\n");
GetKey();
BigCursor();
printf("\nCursor size has been modified, original size will
be restored by passing\n");
printf("original size value to SetCursize function, hit any
key...\n");
GetKey();
SetCurSize(i);
}
SCL1 Version 3.1 - Reference Manual - Page 103
GetDate
-----------------------------------------------------------------
GetDate
-----------------------------------------------------------------
Purpose: Gets the system date.
Prototype: struct DateData * GetDate(void);
Returns: A pointer to the DateData structure defined as
follows:
struct DateData{
int WeekDay; day of the week in numerical format (0=sunday).
int MonthDay; day of the month (1 - 31).
int Month; month number (1 - 12).
int Year; year (1980 - 2099).
};
Parameters: None
Example:
#include <scl1.h>
char *Day[]={"Sunday","Monday","Tuesday","Wednesday","Thursday",
"Friday","Saturday"};
char
*Month[]={"","January","February","March","April","May","June",
"July","August","September","October","November","December"};
main()
{
struct DateData *p;
p=GetDate();
/* p points to DateData structure:
p->WeekDay = day of the week (0=Sunday),
p->MonthDay = day (1-31),
p->Month = month (1-12)
p->Year = year (1980 - 2099).
The month and day numbers reported by GetDate will be used as an
index to the week and months names arrays we have previously
defined.*/
printf("Today is %s, %s %d,%d",Day[p->WeekDay],
Month[p->Month],p->MonthDay,p->Year);
}
SCL1 Version 3.1 - Reference Manual - Page 104
GetDefaultDrive - GetDiskFreeSpace
-----------------------------------------------------------------
GetDefaultDrive
-----------------------------------------------------------------
Purpose: Gets the default disk drive.
Prototype: int GetDefaultDrive(void);
Returns: The default drive number, 0=A, 1=B, etc.
Parameters: None
Example:
#include <scl1.h>
main()
{
int Drive;
Drive=GetDefaultDrive();
printf("The default drive is %c\n",'A'+Drive)
}
-----------------------------------------------------------------
GetDiskFreeSpace
-----------------------------------------------------------------
Purpose: Gets the selected disk drive's free space in bytes.
Prototype: long GetDefaultDrive(int Drive);
Returns: The number of bytes free in the selected drive, "-1"
if TrapInt24 was initialized and a critical error
occurs or "-2" if the drive number is illegal.
Parameter: Drive - drive number as an integer (for example; 0 -
default, 1-A, 2-B, etc.)
Example:
#include <scl1.h>
main()
{
printf("Disk Free Space=%li\n",GetDiskFreeSpace(0));
}
SCL1 Version 3.1 - Reference Manual - Page 105
GetExtendedAscii
-----------------------------------------------------------------
GetExtendedAscii
-----------------------------------------------------------------
Purpose: Changes ALT+Key combination into Extended Ascii
character according to 4 tables
Prototype: unsigned int GetExtendedAscii(unsigned int Key);
Returns: The Ascii Code, if found (<"255"), or original
Scan+Ascii Code, if not found (>"255").
Table 0 is the default. To change table set variable GE_CharTable
to desired table number. The tables have been defined as follows:
Table 0 - ALT+ aeiouvnm12
áéíóúüñÑ¡¿
Table 1 - ALT+ 123456789 qwertyuiop asdfghjkl zxcvbnm
âêîôû£₧ƒ¥ áéíóúÿçÇñÑ àèÄòùÄÉÖÜ äëïöü¡¿
Table 2 - ALT+ 123456789 qwertyuiop asdfghjkl zxcvbnm
╔╗╚╝═║░▒▓ ╦╠╣╩╬█▄▌▐▀ ┌┐└┘─│ΦΘΩ ┬├┤┴┼«»
Table 3 - ALT+ 123456789 qwertyui asdfghjkl zx
αßΓπΣσµτΦ ΘΩδ∞φε∩≡ ±≥≤⌠⌡÷≈√ ²
Parameter: Key - Scan and ASCII code of a key (unsigned int).
Example:
#include <scl1.h>
#include <scl1keys.h>
main()
{
unsigned int key;
do
{
printf("Press an ALT + Key combination...");
key=GetKey();
if((key=GetExtendenAscii(key)) < 255)
{
printf("%c\n",key);
break;
}
else
printf("\nThis key combination has not been defined,
try again!\n:);
}while(1);
}
SCL1 Version 3.1 - Reference Manual - Page 106
GetFiles
-----------------------------------------------------------------
GetFiles
-----------------------------------------------------------------
Purpose: Searches for the files that match the specified
search string and attributes. Sets global variable
GF_FileNumber to the number of files found and
initialize an array of pointers, GF_PointerBuf, which
will point to the filenames.
Prototype: int GetFiles(char *SearchString,int SearchAtr);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
SearchString - char pointer to the desired search string.
SearchAtr - variable that defines the desired search
attributes (integer).
Example:
#include <scl1.h>
main()
{
int i;
if(i=GetFiles("*.*",F_ARCHIVE+F_DIRECTORY))
printf("GetFiles reports error number %i\n",i);
else
{
for(i=0;i < GF_FileNumber;++i)
printf("%s\n",GF_PointerBuf[i]);
}
}
SCL1 Version 3.1 - Reference Manual - Page 107
GetFileMode
-----------------------------------------------------------------
GetFileMode
-----------------------------------------------------------------
Purpose: Gets the selected file's attributes.
Prototype: int GetFileMode(char *Filename,int *FMode);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Filename - pointer to the file's name.
Fmode - pointer to a variable that will hold the file mode
(int).
The following masks has been defined in SCL1.H:
F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME
F_DIRECTORY, F_ARCHIVE
Example:
#include <scl1.h>
char Filename[]="FILE.1";
main()
{
int handle;
unsigned int FMode;
if(CreateFile(Filename,&handle,F_ARCHIVE))
exit(-1);
if(GetFileMode(Filename,&FMode))
exit(-1);
PrintFMode(FMode);
if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN))
exit(-1);
if(GetFileMode(Filename,&FMode))
exit(-1);
PrintFMode(FMode);
if(SetFileMode(Filename,F_ARCHIVE))
exit(-1);
DeleteFile(Filename);
}
PrintFMode(unsigned int FMode)
{
SCL1 Version 3.1 - Reference Manual - Page 108
GetFileMode - GetFilePt
printf("\nFile attributes:\n\n");
if(FMode & F_READ_ONLY)
printf("\tRead Only\n");
if(FMode & F_HIDDEN)
printf("\tHidden\n");
if(FMode & F_SYSTEM)
printf("\tSystem\n");
if(FMode & F_ARCHIVE)
printf("\tArchive\n");
}
-----------------------------------------------------------------
GetFilePt
-----------------------------------------------------------------
Purpose: Gets the file's pointer position.
Prototype: long GetFilePt(int Handle);
Returns: The file pointer position of the file whose handle is
Handle or "-1" if a critical error is detected. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: Handle - Handle returned by DOS when you open or
create a file (integer).
Example:
#include <scl1.h>
#include <string.h>
/* This example creates a file with several names in lower case.
We'll read this file one record at a time into our buffer and
convert the string to uppercase before rewriting it back to
disk. For simplicity, no error checking is shown in the
example */
struct NAME_REC{ /* Our file format */
char Name[7];
}nr; /* nr will be used as a buffer for
converting strings to uppercase */
/* This is the data of the file we will create */
struct NAME_REC names[]={
"John",
"Mary",
"Robert",
"Ann"};
SCL1 Version 3.1 - Reference Manual - Page 109
GetFilePt
main()
{
int handle,i,j;
long fileptr,records;
/* create file */
if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names)))
{
printf("Error creating file\n");
exit(-1);
}
/* Open file for reading and writing */
OpenFile("DEMO.FL",&handle,DOS2_RW);
/* number of records in file = file size/size of structure
NAME_REC */
records=GetFileSize(handle)/sizeof(struct NAME_REC);
/* read one record at a time while there are records */
for(;records > 0;--records)
{
/* save actual file pointer position */
fileptr=GetFilePt(handle);
/* read data, file pointer is automatically moved to next
record by DOS */
ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC));
/* capitalize name */
strupr(nr.Name);
/* move file pointer to original position */
MoveFilePt2Offset(handle,fileptr);
/* write our data, pointer points again to next record */
WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC));
}
CloseFile(handle);
system("type DEMO.FL");
}
SCL1 Version 3.1 - Reference Manual - Page 110
GetFileSize - GetFreeMem
-----------------------------------------------------------------
GetFileSize
-----------------------------------------------------------------
Purpose: Gets the size of the selected file.
Prototype: long GetFileSize(int Handle);
Returns: The size of the file whose handle is Handle or "-1"
if a critical error is detected. (See Appendix "A",
FILE FUNCTIONS, for more information).
Parameter: Handle - Handle returned by DOS when you open or
create a file (integer).
Example: See GetFilePt
-----------------------------------------------------------------
GetFreeMem
-----------------------------------------------------------------
Purpose: Gets the free memory reported by DOS in your system.
Prototype: long GetFreeMem(void);
Returns: The amount of free memory, in bytes, reported by DOS.
Parameters: None
Example:
#include <scl1.h>
main()
{
printf("Available memory: %li",GetFreeMem());
}
SCL1 Version 3.1 - Reference Manual - Page 111
GetKey
-----------------------------------------------------------------
GetKey
-----------------------------------------------------------------
Purpose: Waits and returns the pressed key's Scan/ASCII code.
If the CheckEnhancedKeyb function has been called and
an enhanced keyboard has been detected, GetKey will
also return the Scan/ASCII codes of the extra keys in
the enhanced keyboard.
Prototype: unsigned int GetKey(void);
Returns: The Scan/Ascii code of the pressed key. See Appendix
"D" for the variables defined in SCL1KEYS.H.
Parameters: None
Example:
#include <scl1.h>
#include <scl1keys.h>
main()
{
unsigned int Key;
if(CheckEnhancedKeyb())
printf("Enhanced Keyboard\n");
else
printf("No Enhanced Keyboard available\n");
do
{
switch(Key=GetKey())
{
case ENH_ENTER:
case ENTER:
printf("Enter\n");
break;
case ENH_DEL:
case DEL:
printf("Delete\n");
break;
case ENH_INS:
case INS:
printf("Insert\n");
break;
case ENH_END:
case END:
printf("End\n");
break;
SCL1 Version 3.1 - Reference Manual - Page 112
GetKey
case ENH_CTRLEND:
printf("Enhanced Control End\n");
break;
case CTRLEND:
printf("Control End\n");
break;
case F11:
printf("F11\n");
break;
case F12:
printf("F12\n");
break;
case SHIFTF11:
printf("Shift F11\n");
break;
case SHIFTF12:
printf("Shift F12\n");
break;
case CTRLF11:
printf("Control F11\n");
break;
case CTRLF12:
printf("Control F12\n");
break;
case ALTF11:
printf("Alt F11\n");
break;
case ALTF12:
printf("Alt F12\n");
break;
default:
printf("%X\n",Key);
break;
}
}while(Key != ESC);
}
SCL1 Version 3.1 - Reference Manual - Page 113
GetString
-----------------------------------------------------------------
GetString
-----------------------------------------------------------------
Purpose: Saves the cursor position, displays a prompt, the
current buffer contents and fills the buffer with
keyboard input. If variable GS_Insert is set to "1"
prior to calling GetString, it will start in the
insert mode. When an entry has been made into the
buffer the variable GS_Edit is set to "1". If GS_Beep
is set to "1" the speaker will sound if an invalid
key is pressed. The buffer must be initialized.
Prototype: int GetString(int PColor,int PRow,int PCol,
char* Prompt,int FColor,int FRow,int FCol,
int MaxChar,unsigned int CharType,char *Buffer);
Returns: The number of characters in Buffer or "-1" if the Esc
key is pressed.
Parameters:
PColor - color attribute of the prompt (integer).
PRow - row position where to display the prompt (integer).
PCol - column position where to display the prompt (int).
Prompt - pointer to the prompt to be displayed (char).
FColor - color attribute of the field (integer).
FRow - row position where to display the field (integer).
FCol - column position where to display the field (int).
MaxChar - length of the input field (integer).
CharType - mask of valid characters as described in
CheckChar.
Buffer - pointer to the buffer to be used to store the field,
it must be one digit larger than the field's size.
Example:
#include <scl1.h>
char Buffer[32];
main()
{
GetString(7,10,20,"Name:",0x70,10,28,31,CC_ANY,Buffer);
}
SCL1 Version 3.1 - Reference Manual - Page 114
GetTime - Huge2Far
-----------------------------------------------------------------
GetTime
-----------------------------------------------------------------
Purpose: Gets the system time. Sets global variables GT_Hours,
GT_Minutes, GT_Seconds and GT_Hundredths to the
system time.
Prototype: char *GetTime(void);
Returns: A pointer to a buffer that holds the system time in
ASCII.
Parameters: None
Example:
#include <scl1.h>
main()
{
WriteScreen(0x7,3,3,"Time:");
WriteScreen(0x7,3,9,GetTime());
}
-----------------------------------------------------------------
Huge2Far
-----------------------------------------------------------------
Purpose: Converts a huge pointer to a far pointer. It is used
to convert huge pointers before passing them to an
SCL1 function. (Works only in the compact and large
models of the Microsoft C version of SCL1). The
function prototype is declared in SCL1HUGE.H
Prototype: far* Huge2Far(huge* p);
Returns: A far pointer.
Parameter: p - huge pointer to be converted.
Example:
#include <SCL1HUGE.H>
main()
{
char *p;
huge *h;
p=Huge2Far(h);
}
SCL1 Version 3.1 - Reference Manual - Page 115
HideMouse - ShowMouse
-----------------------------------------------------------------
HideMouse, ShowMouse
-----------------------------------------------------------------
Purpose: Hides or removes the mouse cursor from the screen
(HideMouse) or makes mouse cursor visible
(ShowMouse).
Prototype: void HideMouse(void);
void ShowMouse(void);
Returns: Nothing
Parameters: None
Example:
#include <scl1.h>
main()
{
InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */
if(MSE_MouseFl)
{
printf("We have a mouse, click the left button to turn
mouse cursor off.\n");
WaitKeyMouse();
HideMouse();
printf("Click again to turn mouse cursor on.\n");
WaitKeyMouse();
ShowMouse();
printf("Click to exit.\n");
WaitKeyMouse();
}
else
printf("We don't have a mouse\n");
}
SCL1 Version 3.1 - Reference Manual - Page 116
InitDrive - InitMouse
-----------------------------------------------------------------
InitDrive
-----------------------------------------------------------------
Purpose: Verifies if a disk drive has been assigned more than
one logical drive letters and sets the drive to
respond to a specified letter. Requires DOS 3.2 or
higher. This function is useful to prevent DOS from
displaying the "Insert Diskette in Drive X:".
Prototype: int InitDrive(int Drive);
Returns: If an error has occurred it returns "-1" else it
returns "0".
Parameter: Drive - drive number as an integer (for example; 0 -
default, 1-A, 2-B, etc.)
Example:
InitDrive(1); /* makes sure drive A: is ready */
-----------------------------------------------------------------
InitMouse
-----------------------------------------------------------------
Purpose: Initializes the mouse for further use of the mouse
functions. When you exit the program it takes care of
resetting the mouse.
Prototype: int InitMouse(int Cursor);
Returns: If an error has occurred it returns "-1".
Parameter: Cursor - this parameter tells InitMouse how to handle
the mouse cursor. The following variables have been
defined in SCL1.H;
IM_SHOW - means to show the mouse cursor (int).
IM_NO_SHOW - means not to show the mouse cursor
(integer).
Example: See HideMouse
SCL1 Version 3.1 - Reference Manual - Page 117
InitUserError
-----------------------------------------------------------------
InitUserError
-----------------------------------------------------------------
Purpose: Initialize user defined error codes for use with the
ErrorBox function. You can also redefine the standard
ErrorBox messages.
Prototype: void InitUserError(struct ErrorMess *p);
Returns: Nothing
Parameters: The Error Message information is placed in an array
of structures as follows: (The array of structures is
terminated with a "0").
struct ErrorMess{
int ErrorNum; An integer value for the error number. User
defined values shall be above 256. If a
predefined error message is redefined, the
function will use the new values.
char *Message; Pointer to the defined error message's text.
};
Example: See ErrorShadowOn/Off
-----------------------------------------------------------------
InitVideo
-----------------------------------------------------------------
Purpose: Initialize video monitor to the alphanumeric display
mode.
Prototype: void InitVideo (void);
Returns: Nothing
Parameters: None
Example:
#include <scl1.h>
main()
{
InitVideo();
printf("SCL1's InitVideo function has initialized your
monitor\nto it's default alphanumeric mode.\n");
}
SCL1 Version 3.1 - Reference Manual - Page 118
InitWData
-----------------------------------------------------------------
InitWData
-----------------------------------------------------------------
Purpose: This version of SCL1 provides another way of defining
and using windows. In these windows you can specify
shadow effect, frames, grow and shrinking effects,
justification method, etc. This information can now
be specified using a WData type structure. Once the
window is defined you can use the CreateWindow
function to create the window; ClearWindow to clear
the window; DestroyWindow to destroy the window and
WriteWindow to write information to the window. This
function provides an easy way to initialize this
structure. The structure elements HorSize, VerSize,
HorCenter, VerCenter and Buffer are automatically
initialized.
Prototype: void InitWData(WData *wd,int Color,int Style,
int UpperRow,int LeftCol,int LowerRow,
int RightCol,int FrameType,int TitleColor,
char * Title);
Returns: Nothing
Parameters: The window data is stored in a structure WData as
follows:
typedef struct{
int Color; Color to be used for the window.
int Style; Defines the way the window will be
displayed. Refer to the Style description
below.
int FrameType; Frame type to be used.
int UpperRow; Upper left row position of the window.
int LeftCol; Upper left column position of the window.
int LowerRow; Lower right row position of the window.
int RightCol; Lower right column position of the window.
int TitleColor; Color to be used for displaying the title.
int *Title; Title's text.
SCL1 Version 3.1 - Reference Manual - Page 119
InitWData
int HorSize; Structure element (internal) that holds the
window's horizontal size excluding the
frame. This information can be used to
calculate the window's center for writing
text.
int VerSize; Structure element (internal) that holds the
window's vertical size excluding the frame.
int HorCenter; Structure element (internal) that holds the
window's horizontal center.
int VerCenter; Structure element (internal) that holds the
window's vertical center.
char *Buffer; Buffer for storing the screen area contents.
}WData;
The following parameters are passed to the function:
WData - the address of the WData structure.
Color - color to be used for the window (integer).
Style - defines the way the window will be displayed. You can
concatenate different style options using the "or" (|)
operator between options. The following style options have
been defined in SCL1.H:
W_SAVE - save the screen area defined for the window.
W_CLEAR - clear screen area to the defined color.
W_FRAME - add a frame to the window.
W_GROW - use a growing effect when displaying the window.
W_SHRINK - use a shrinking effect when removing the
window.
W_SHADOW - display a shadow effect.
UpperRow - upper left row position of the window (integer).
LeftCol - upper left column position of the window (integer).
LowerRow - lower right row position of the window (integer).
RightCol - lower right column position of the window (int).
FrameType - any of the frame types defined in Box or GSSBox
(int).
SCL1 Version 3.1 - Reference Manual - Page 120
InitWData
TitleColor - color to be used for displaying the Title (int).
Title - Title to be displayed (char pointer).
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
WData wd;
/* Define a window from rows 5 to 17, columns 19 to 59, with
frame type 3, white black colors, and with the following
styles; save screen area, draw a shadow effect, draw a frame,
grow when opening, shrink when closing and add title. */
InitWData(&wd,WHITE_BLACK,W_SAVE | W_SHADOW | W_FRAME | W_GROW |
W_SHRINK,5,28,19,73,3,BLACK_WHITE," WINDOW TITLE ");
CreateWindow(&wd); /* create the window */
/* Display centralized text in the first row of the window, use
HorCenter as column parameter to centralize text use HorSize
so that the Horizontal window size is used as Count
parameter. */
WriteWindow(&wd,1,wd.HorCenter,wd.HorSize,W_CENTER,"Text can
be\ncentralized...");
WaitTime(300);
/* Display left justified string */
WriteWindow(&wd,5,1,wd.HorSize,W_LEFT,"Left\njustified...");
WaitTime(300);
/* Display right justified string. Use HorSize to know the
window right column value. */
WriteWindow(&wd,8,wd.HorSize-2,wd.HorSize,W_RIGHT,"or right\n
justified...");
WaitTime(300);
SCL1 Version 3.1 - Reference Manual - Page 121
InitWData - Int24ShadowOff - Int24ShadowOn
/* Clear the window */
ClearWindow(&wd);
/* Display string with new lines and tab control codes. Use
VerCenter to centralize the string vertically. */
WriteWindow(&wd,wd.VerCenter,1,wd.HorSize,W_LEFT,"New lines\n
and\t\tTab control codes are supported...");
WaitTime(300);
ClearWindow(&wd);
/* This string is longer than window size, it will be clipped */
WriteWindow(&wd,wd.VerCenter,22,wd.HorSize,W_LEFT,"This line will
be clipped...");
WaitTime(300);
/* Remove window from screen */
DestroyWindow(&wd);
}
-----------------------------------------------------------------
Int24ShadowOff, Int24ShadowOn
-----------------------------------------------------------------
Purpose: Enable or disable a shadow effect when using the
TrapInt24 function. After any of these functions is
called, all TrapInt24 messages will be displayed with
(or without) a shadow effect.
Prototype: void Int24ShadowOff(void);
void Int24ShadowOn(void);
Returns: Nothing.
Parameters: None.
See TrapInt24 and SetTrapInt24Colors.
SCL1 Version 3.1 - Reference Manual - Page 122
I24_SetUserLang
-----------------------------------------------------------------
I24_SetUserLang
-----------------------------------------------------------------
Purpose: Modify the default TrapInt24 error messages with your
own error messages.
Prototype: void I24_SetUserLang(char *prompt1,int offset1,
unsigned int key1,char *prompt2,int offset2,
unsigned int key2,struct ErrorMess *em)
Returns: Nothing
Parameters: The error messages are defined in a null terminated
array of structures as follows:
struct ErrorMess{
int ErrorNum; Error number of the message to modify.
char *Message; Pointer to the new error message.
};
The following are the default error messages:
ERROR DESCRIPTION
0 Write-protected diskette!
2 Drive not ready!
4 CRC Data error
6 Seek error
8 Sector not found
9 Printer out of paper!
10 Write fault
11 Read fault
12 General failure
0 Printer not ready!
0 Unknown Critical Error
The following parameters are passed to the function:
prompt1 - char pointer to the first prompt ("Retry") action.
offset1 - position from the border of the box where to
display the first prompt (integer).
key1 - key to be used for selecting prompt1 (unsigned int).
prompt2 - char pointer to the second prompt ("Cancel")
action.
SCL1 Version 3.1 - Reference Manual - Page 123
I24_SetUserLang - KeyReady
offset2 - position from the border of the box where to
display the second prompt (integer).
key2 - key to be used for selecting prompt2 (unsigned int).
em - pointer to the ErrorMess structure.
Example:
static struct ErrorMess CtrErrs[]={ /* error code, message */
0,"¡Disco protegido!",
2,"¡El lector no está listo!",
4,"Error de data en disco",
6,"Error buscando en disco",
8,"Imposible encontrar sector",
9,"¡Impresora sin papel!",
10,"Error de escritura",
11,"Error de lectura",
12,"Falla general",
0,"¡La impresora no está lista!",
0,"Error crítico desconocido",
0};
I24_SetUserLang("< TRATAR >",6,0x1454,"< CANCELAR
>",18,0x2e43,CtrErrs);
-----------------------------------------------------------------
KeyReady
-----------------------------------------------------------------
Purpose: Scans the BIOS keyboard buffer for unprocessed
keystrokes.
Prototype: unsigned int KeyReady(void);
Returns: The Scan/Ascii code of key in the BIOS buffer or "0"
if it is empty.
Parameters: None
Example:
#include <scl1.h>
main()
{
while(!KeyReady())
printf("No key has been pressed!\n");
ClearKeyBuf();
}
SCL1 Version 3.1 - Reference Manual - Page 124
KeyStatus
-----------------------------------------------------------------
KeyStatus
-----------------------------------------------------------------
Purpose: Returns the shift, control and toggle key status.
Supports extended keyboards if CheckEnhancedKeyb has
been previously called.
Prototype: unsigned char KeyStatus(void);
Returns: The return value AND the following masks, defined in
SCL1KEYS.H, are ">0" if the key is toggled or
pressed.
The mask values for standard keyboards defined in
SCL1KEYS.H are: INSERT, CAPSL, NUML, SCROLL, ALT,
CTRL, LSHIFT and RSHIFT.
The additional mask values for enhanced keyboards
defined in SCL1KEYS.H are: LEFT_CTRL, LEFT_ALT,
RIGHT_CTRL, RIGHT_ALT, SCROLL_DOWN, NUML_DOWN,
CAPSL_DOWN and SYSREQ.
Example:
#include <scl1.h>
#include <scl1keys.h>
/* shows the use of the KeyStatus functions */
main()
{
unsigned int KStat,OldKStat;
KStat=KeyStatus();
do
{
OldKStat = KStat;
if(KStat & ALT)
printf("\n\nALT ON ");
else
printf("\n\nALT OFF");
if(KStat & LSHIFT || KStat & RSHIFT)
printf("\t\tSHIFT ON ");
else
printf("\t\tSHIFT OFF");
SCL1 Version 3.1 - Reference Manual - Page 125
KeyStatus
if(KStat & CTRL)
printf("\tCONTROL ON ");
else
printf("\tCONTROL OFF");
if(KStat & INSERT)
printf("\tINSERT ON ");
else
printf("\tINSERT OFF");
if(KStat & CAPSL)
printf("\nCAPS LOCK ON ");
else
printf("\nCAPS LOCK OFF");
if(KStat & NUML)
printf("\tNUM LOCK ON ");
else
printf("\tNUM LOCK OFF");
if(KStat & SCROLL)
printf("\tSCROLL LOCK ON ");
else
printf("\tSCROLL LOCK OFF");
printf("\n\nPress any other key to exit\n");
do
{
KStat=KeyStatus();
}while(KStat == OldKStat && !KeyReady());
if(KeyReady()==INS)
ClearKeyBuf();
}while(!KeyReady());
ClearKeyBuf();
}
SCL1 Version 3.1 - Reference Manual - Page 126
LeapYear
-----------------------------------------------------------------
LeapYear
-----------------------------------------------------------------
Purpose: Determines if a year is leap or not.
Prototype: int LeapYear(int year);
Returns: Returns "1" if the year passed as a parameter is leap
or "0" if it is not leap.
Parameter: year - year in the YYYY format (integer).
Example:
/* This is the source of the DaysPerMonth function */
void DaysPerMonth(year,month)
{
switch (month)
{
case 1:
case 3:
case 5:
case 7:
case 8:
case 10:
case 12:
return(31);
case 4:
case 6:
case 9:
case 11:
return(30);
case 2:
return(28+LeapYear(year));
}
}
SCL1 Version 3.1 - Reference Manual - Page 127
LineEditor
-----------------------------------------------------------------
LineEditor
-----------------------------------------------------------------
Purpose: A full featured line editor. You can define most
display parameters such as; where to display a
prompt, size of the field, size of the display,
colors, cursor size, default editing mode, etc.
Prototype: int LineEditor(int Message,LEData *p,...);
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The line editor information must be
given in a structure defined as type LEData. The
structure elements are as follows:
typedef struct{
int PColor; Color attribute for the prompt.
int PRow; Row position for the prompt's
display.
int PCol; Column position for the prompt's
display.
char *Prompt; Char pointer to the prompt.
int FColor; Color attribute for the field.
int FRow; Row position for the field's
display.
int FCol; Column position for the field's
display.
unsigned int FLength; Number of characters to display.
unsigned int FSize; Maximum number of characters of the
field. If FSize is larger than
FLength, the display will scroll
horizontally when the cursor
reaches the end of the display
length.
SCL1 Version 3.1 - Reference Manual - Page 128
LineEditor
int CType; Type of characters to be accepted.
Please refer to CheckChar for a
description of the values defined
in SCL1.H.
int MaskFn; Flag to instruct the function to
accept or discard the characters
defined in the MaskArray array. A
"0" value will accept the
characters and a "1" value will
discard them.
char *MaskArray; Array of mask characters (null
terminated).
char *Buffer; Buffer that holds the information
to be edited.
char *FormatC; String that holds the characters to
be used as format characters (such
as / to delimit date fields, etc.).
unsigned int *ExitKeys; Null terminated array of unsigned
integer Scan/Ascii values of the
keys to exit.
int InsFlag; Flag to instruct the function of
the default edit mode. ("1" =
Insert, "0" = typeover).
int InsertCur; Size of cursor when insert mode is
toggled ("0" = none, "1" = normal,
"2" = block sized).
int TypeOverCur; Size of cursor when typeover mode
is toggled ("0"= none, "1" =
normal, "2" = block sized).
int CPaint; Color to be used to mark a group of
characters from the position
defined by StartPos to EndPos. The
CPaint value can be used to
construct character blocks.
unsigned int StartPos; Start position of conditional
paint.
unsigned int EndPos; End position of conditional paint.
unsigned int EventInfo; Information about pressed keys.
SCL1 Version 3.1 - Reference Manual - Page 129
LineEditor
unsigned int Position; Contains the current cursor
position within the buffer (or
offset).
unsigned int Scroll; Horizontal scroll counter, keeps
track of the cursor position when
the field size is larger than the
field length.
int Edited; Flag that keeps track of the field
activity. A value of "0" means
that the field has not been edited
and a value of "1" means that the
field has been edited.
}LEData;
Messages:
Messages that can be sent to the LineEditor function:
LE_INIT - Initialize the LEData structure to NULL and sets
the following default values:
PColor - set to white characters in a black background or
the normal color set by SetDialogColors.
FColor - set to black characters in a white background or
the reversed color set by SetDialogColors.
FLength and FSize - set to 40 columns.
CType - set to CC_ANY, accept any character.
Buffer - set to use a default internal buffer called
DefBuf.
ExitKeys - set to the default exit keys.
InsFlag - set to the typeover mode.
InsertCur - set to a value of "2".
LE_DRAW - display the prompt and current edit buffer's
information.
LE_UPDATE_FIELD - display the current edit buffer's contents.
LE_ACTIVE - edit the contents of the field buffer. The
following edit keys have been defined:
SCL1 Version 3.1 - Reference Manual - Page 130
LineEditor
Key Action
Left Arrow cursor one position to the left.
Right Arrow cursor one position to the right.
END cursor to end of field.
HOME cursor to beginning of field.
INSERT toggle insert mode on/off.
BACKSPACE erase the character at current cursor
position. Move remaining text to the
left.
CTRL+Left cursor to previous word
CTRL+Right cursor to next word
LE_KEY - the parameter passed with this messages (Scan+Ascii
code of the key) is a key value that performs as if the key
has been pressed.
LE_DATA - the parameter passed with this messages is an ASCII
value that performs as if that character has been typed.
LE_POSITION_BEGIN - move cursor the start of the edit buffer.
LE_POSITION_END - move cursor to the end of the edit buffer.
LE_POSITION_UP - move cursor one position forward.
LE_POSITION_DOWN - move cursor one position backwards.
LE_SET_POSITION - set the cursor position.
LE_CHARS_UP - moves all the text from the current cursor
position one space forward.
LE_CHARS_DOWN - moves all the text in the field from the
current cursor position one space backwards.
LE_CLEAR - clear the editor's buffer.
LE_RESET - when this message is sent the field contents
variables are reset to the default value. If the exit keys
have not been defined they are set to the default exit keys.
Messages that LineEditor can return:
LE_OK - the requested action has been successfully performed.
LE_EXIT_KEY - a key defined as an exit key has been pressed.
LE_MOUSE_EVENT - the mouse has been clicked after pointing
outside the Line Editor field.
SCL1 Version 3.1 - Reference Manual - Page 131
LineEditor
LE_BUFFER_END - you have reached the buffer's maximum size.
LE_BUFFER_BEGIN - you have reached the beginning of the edit
buffer.
LE_ILLEGAL_KEY - a key that has not been defined as an exit
key or that is not a legal key as defined for that field has
been pressed.
LE_BUFFER_FULL - the edit buffer is full.
LE_ILLEGAL_POSITION - you have requested to move the cursor
passed the maximum defined field length or to the left of the
beginning position.
LE_NEW_POSITION - a legal editing function is performed.
LE_MY_MOUSE - response to a LE_CHECK_MOUSE message if the
mouse has been clicked after pointing to the field area
defined by the function.
LE_DEL_NULL - you have pressed the delete key when the cursor
has reached the buffer end.
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
/* Shows the use of LineEditor function. See the example 2 for
another example of LineEditor */
unsigned int ExitKeys[]={ENTER,ESC,0};
main()
{
LEData led;
int Mess;
char buffer[81];
Cls(WHITE_BLACK,CLS_ALL); /* clear screen */
memset(buffer,0,sizeof(buffer)); /* initialize buffer */
/* initialize Line Editor structure */
LineEditor(LE_INIT,&led);
SCL1 Version 3.1 - Reference Manual - Page 132
LineEditor
/* modify prompt and field position */
led.PRow=led.FRow=12;
led.PCol=25;
led.FCol=35;
led.FLength=20;/* the field's screen length is of 20 characters*/
led.FSize=80; /* but up to 80 characters can be entered, the
data entry field will scroll automatically */
led.Prompt="Filename:"; /* prompt */
led.CType=CC_PATH | CC_CAPITALIZE; /* type of valid characters*/
led.Buffer=buffer; /* use our buffer */
led.ExitKeys=ExitKeys; /* our defined exit keys */
PushCursor(); /* save cursor */
LineEditor(LE_DRAW,&led); /* draw */
/* Main loop: send ACTIVE message, LineEditor constantly returns
information */
do
{
Mess=LineEditor(LE_ACTIVE,&led);
if(Mess==LE_ILLEGAL_KEY) /* illegal key? */
TSound(440,10); /* beep */
/* loop until an exit key is pressed */
}while(Mess != LE_EXIT_KEY);
PopCursor();
Cls(WHITE_BLACK,CLS_ALL); /* clear screen */
}
/****************************************************************
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
/* Shows the use of LineEditor function using a mask to define
acceptable characters. A '@' accepts letters and # accepts
digits, * accepts any character. */
char mask[]="@@##@"; /* mask to be used */
unsigned int ExitKeys[]={ENTER,ESC,0}; /* LineEd exit keys */
main()
{
LEData led;
int Mess;
SCL1 Version 3.1 - Reference Manual - Page 133
LineEditor
char buffer[6];
Cls(WHITE_BLACK,CLS_ALL); /* clear screen */
memset(buffer,0,sizeof(buffer)); /* initialize buffer */
/* initialize Line Editor structure */
LineEditor(LE_INIT,&led);
/* modify prompt and field position */
led.FRow=12;
led.FCol=35;
led.FLength=5; /* the field's screen length is of 5 characters*/
led.FSize=5;
led.CType=CC_ANY; /* type of valid characters */
led.Buffer=buffer; /* use our buffer */
led.ExitKeys=ExitKeys; /* our defined exit keys */
PushCursor(); /* save cursor */
LineEditor(LE_DRAW,&led); /* draw */
/* Main loop: send ACTIVE message, LineEditor constantly
returns information */
do
{
Mess=LineEditor(LE_ACTIVE,&led);
if(Mess==LE_ILLEGAL_KEY) /* illegal key? */
TSound(440,10); /* beep */
CheckMask(&led); /* call our function to check mask*/
/* loop until an exit key is pressed */
}while(Mess != LE_EXIT_KEY);
Cls(WHITE_BLACK,CLS_ALL); /* clear screen */
}
CheckMask(LEData *led)
{
int i;
/* each time called this function will check the string in
LineEditor and compare it with the mask */
i=strlen(led->Buffer)-1;
SCL1 Version 3.1 - Reference Manual - Page 134
LineEditor
while(i >= 0)
{
switch(mask[i])
{ /* digits only */
case '#':
if(!isdigit(led->Buffer[i]))
goto Invalid;
break;
case '@': /* letters only */
if(!isalpha(led->Buffer[i]))
goto Invalid;
break;
case '*': /* accept anything */
return;
}
--i;
}
return;
/* In case an invalid character is detected we'll move
LineEditor position to the invalid character. If insert mode
is on (InFlag) we'll send the CHARS_DOWN message to
LineEditor so that all characters that follow the invalid
character are moved down. If insert mode is off we'll copy a
space character to the current position. */
Invalid:
{
led->Position=i;
if(led->InsFlag)
LineEditor(LE_CHARS_DOWN,led);
else
led->Buffer[i]=' ';
LineEditor(LE_DRAW,led); /* redraw */
TSound(440,10);
}
}
SCL1 Version 3.1 - Reference Manual - Page 135
LinkedList
-----------------------------------------------------------------
LinkedList
-----------------------------------------------------------------
Purpose: Manages linked lists.
Prototype: int LinkedList(int Mess,LLData *ld,...);
Returns: This is a dialog derived function. See Appendix "E"
for a description of the general operation of these
functions. Returns the messages described in the
Messages section.
Parameters: The linked list information is given in structures
type LLData as follows:
typedef struct{
unsigned int DataSize; The size of the data block.
char *Data; Pointer to user defined data.
unsigned int Nodes; Variable (internal) that holds the
quantity of nodes in the list.
unsigned int ActiveNode; Variable (internal) that holds the
active node number.
LLNODE *Head; Pointer (internal) to the first
node of the list.
LLNODE *Tail; Pointer (internal) to the last node
of the list.
LLNODE *Position; Pointer (internal) to the active
node of the list.
}LLData;
The structure LLNODEtag can be checked to find out the pointers
to the next and previous nodes. For most applications you will
not have to worry about this structure.
struct LLNODEtag{
struct LLNODEtag *Next; Pointer to the next list node.
struct LLNODEtag *Prev; Pointer to the previous list node.
unsigned int DataSize; The size of the data block.
char *Data; Pointer to user defined data.
}
SCL1 Version 3.1 - Reference Manual - Page 136
LinkedList
Messages:
The following messages can be sent to LinkedList:
LL_INIT - initialize the LLData structure to null.
LL_ADD - add a node to the list.
LL_NEXT - move to the next node in the list.
LL_PREVIOUS - move to the previous node in the list.
LL_FIRST - move to the first node in the list.
LL_LAST - move to the last node in the list.
LL_DELETE - delete a node from the list.
LL_DELETE_ALL - delete all nodes.
LL_INSERT - insert a node in the list.
LL_SET_POSITION - set the node pointer to a desired position.
LL_REPLACE - replace a node in the list.
LL_SAVE_POSITION - saves a position in the list for further
reference.
LL_RESTORE_POSITION - returns to the node previously saved
with the LL_SAVE_POSITION message.
The following messages can be returned by LinkedList:
LL_OK - no errors were found while performing a requested
action.
LL_MEM_ERROR - there is not enough memory to store the linked
list.
LL_LAST_NODE - you have reached the last node of the list.
LL_FIRST_NODE - you have reached the beginning of the list.
LL_EMPTY_LIST - the linked list is empty.
LL_ILLEGAL_POSITION - you have requested to move the record
pointed to an illegal position.
SCL1 Version 3.1 - Reference Manual - Page 137
LinkedList
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <string.h>
#include <malloc.h>
/* This example shows the use of the LinkedList to create and
manage a linked list */
main()
{
LLData ld;
char buffer[20];
int i,Mess;
unsigned int key=0;
InitVideo();
LinkedList(LL_INIT,&ld); /* init */
/* add 20 elements to list */
for(i=0;i < 20;++i)
{
sprintf(buffer,"line #%i",i);
ld.DataSize=strlen(buffer)+1; /* elements can have
different sizes */
ld.Data=buffer; /* point to our data */
LinkedList(LL_ADD,&ld);
}
LinkedList(LL_FIRST,&ld); /* move to first position */
printf("%s size:%i\r\n",ld.Data,ld.DataSize);
Mess=LL_OK;
do
{
switch(key) /* translate keystroke to message */
{
case UP:
Mess=LL_PREVIOUS;
break;
case DOWN:
Mess=LL_NEXT;
break;
case HOME:
Mess=LL_FIRST;
SCL1 Version 3.1 - Reference Manual - Page 138
LinkedList
break;
case END:
Mess=LL_LAST;
break;
case INS:
/* let user insert new element */
memset(buffer,0,sizeof(buffer));
if(DialogBox(7,"Text:",0x70,10,CC_ANY,buffer)!=-1)
{
ld.Data=buffer; /* points to new data */
ld.DataSize=strlen(buffer)+1; /* equals size in
bytes */
Mess=LinkedList(LL_INSERT,&ld);
}
Mess=0;
break;
case DEL:
Mess=LL_DELETE;
break;
case ENTER:
/* let user modify data */
strcpy(buffer,ld.Data);
if(DialogBox(7,"Text:",0x70,10,CC_ANY,buffer)!=-1)
{
ld.Data=buffer;
ld.DataSize=strlen(buffer)+1;
/* replace previous data */
Mess=LinkedList(LL_REPLACE,&ld);
Mess=0;
}
break;
case F2:
/* let user modify position */
if(DialogBox(7,"Position:",0x70,10,CC_DIGIT,buffer)!=-1)
Mess=LinkedList(LL_SET_POSITION,&ld,atoi(buffer));
break;
default:
Mess=0;
break;
}
SCL1 Version 3.1 - Reference Manual - Page 139
LinkedList - ListManager
/* send message to LinkedList */
if(Mess)
{
Mess=LinkedList(Mess,&ld);
/* display data at current position,
ld.Data points to our data
ld.DataSize equals size in byes */
if(Mess!=LL_EMPTY_LIST)
printf("%s size:%i\r\n",ld.Data,ld.DataSize);
else
printf("Empty list\r\n"); /* no data */
}
}while((key=GetKey()) != ESC);
LinkedList(LL_DELETE_ALL,&ld);
}
-----------------------------------------------------------------
ListManager
-----------------------------------------------------------------
Purpose: Displays a list of items and permits user selection
of items.
Prototype: int ListManager(int NColor,int RColor,int Number,
int Length,int Selection,int Lines,int Cols,
struct ItemList*p);
Returns: The number of the selected item.
Parameters: The Item List message information must be given as an
array of structures as follows:
struct ItemList{
int Row; Row position of where to display the item.
int Col; Column position where to display the item.
char *String; Char pointer to the item text to be displayed.
};
The parameters passed to the function are:
NColor - color for the normal display of items (integer).
RColor - color for the highlighted item (integer).
SCL1 Version 3.1 - Reference Manual - Page 140
ListManager
Number - number of items defined (integer).
Length - length of the items (integer).
Selection - default selection (integer).
Lines - number of lines to be displayed (integer).
Cols - number of columns to be displayed (integer).
ItemList - pointer to the item list structure.
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=BLACK_WHITE;
int Color2=WHITE_BLACK;
struct ItemList il[]={
10,10,"Item #1",
10,20,"Item #2",
10,30,"Item #3",
12,10,"Item #4",
12,20,"Item #5",
12,30,"Item #6",
};
main()
{
int ItemSelected;
ItemSelected=ListManager(Color1,Color2,6,6,1,2,3,il);
}
See also ListWindow.
SCL1 Version 3.1 - Reference Manual - Page 141
ListWindow
-----------------------------------------------------------------
ListWindow
-----------------------------------------------------------------
Purpose: Displays an array of items in a window in columnar
form. The user can use the keyboard or mouse to tag
or select a desired item. For a large list of items,
scroll bars are displayed to indicate that there are
items not shown.
Prototype: int ListWindow(int Message,LWData *p,...);
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The list window information is given
in a structure defined as type LWData as follows:
typedef struct{
int NColor; Color for normal display.
int RColor; Color for reversed display.
int UpperRow; Upper row position of the window.
int LeftCol; Left column position of the window.
int LowerRow; Lower row position of the window.
int RightCol; Right column position of the
window.
int FrameType; Frame type as defined in Box.
int ScrollBar; Flag to select drawing scroll bars
at the bottom of the display.
int BarColor; Color for the scroll bars.
char **Array; Pointer to a null terminated array
of pointers to be displayed.
char *TagArray; Array that holds which items have
been tagged. If a null pointer is
specified no tagging will be
permitted. Array element values of
"0" and "1" indicate the status for
untagged and tagged.
SCL1 Version 3.1 - Reference Manual - Page 142
ListWindow
int TagColor; Color for displaying a tagged item.
char *Title; Char pointer to text to be
displayed as a window title.
int TitleColor; Color for the title's display.
unsigned int *ExitKeys; Null terminated array of keys to
exit the function.
int StaticWidth; A value of "0" means that the
number of columns will be
determined by the length of the
items, a value of "1" sets the
width of the columns to the value
defined with ColumnWidth.
unsigned int Items; Variable (internal) that holds the
quantity of items in the array.
unsigned int ColumnWidth; Width of each column to be
displayed.
unsigned int FirstItem; Variable (internal) that holds the
position of the first array
element.
unsigned int Position; Variable (internal) that holds the
active position of the display.
This element should not be modified
by the calling program but can be
read.
unsigned int *ExitKeys; Array of keys to exit the function.
int WindowLines; Number of lines in the List Window
(used internally).
int WindowCols; Variable (internal) that holds the
number of columns in the List
Window.
int TotalCols; Variable (internal) that holds the
maximum number of columns in the
window.
int TotalWindowItems; Variable (internal) that holds the
number of items.
SCL1 Version 3.1 - Reference Manual - Page 143
ListWindow
int OldHBlock; Variable (internal) that holds the
position of the relative position
indicating scroll bar block).
unsigned int EventInfo; Information about the keys that
have been pressed.
}LWData;
Messages:
The following messages can be sent to ListWindow:
LW_INIT - initialize the LWData structure to NULL and set the
following default values:
NColor - set to white characters in a black background or
the normal color set by SetDialogColors.
RColor - set to black characters in a white background or
the reversed color set by SetDialogColors.
LowerRow and RightCol - one less than the screen length.
FrameType - set to frame type "1" (single line).
ScrollBar - set to draw scroll bars.
BarColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
TagColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
TitleColor - set to white characters in a black
background or the normal color set by SetDialogColors.
OldHBlock - set to "-1".
LW_DRAW - display the list window.
LW_WRITE - displays the list of items to the screen.
LW_ACTIVE - browse through the displayed items and permit the
selection or tagging of them using the keyboard as follows:
SCL1 Version 3.1 - Reference Manual - Page 144
ListWindow
Key Action
Up Arrow cursor one item up.
Down Arrow cursor one item down.
Left Arrow cursor one item to the left.
Right Arrow cursor one item to the right.
END cursor to end of list.
HOME cursor to beginning of list.
Page Up cursor one screen up.
Page Down cursor one screen down.
LW_DRAW_BORDER - draw the List Window's border.
LW_POSITION_BEGIN - move cursor to the first item.
LW_POSITION_END - move cursor to the last item.
LW_POSITION_UP - move cursor to the previous item.
LW_POSITION_DOWN - move cursor to the next item.
LW_SET_POSITION - move cursor to a specific item. The item
number is passed as a parameter.
LW_CLS - clear the list window data area.
LW_CHECK_MOUSE - check if the mouse has been clicked after
pointing to the area defined by the function.
LW_RESET - reset the position variables to default values. If
exit keys have not been defined they are set to the default
exit keys.
LW_MBAR_CHARS - this message is used to change the characters
used for the scroll bars display. Default characters are
defined in header file SCL1.H as LW_MBAR_DEF (character for
the background) and LW_THUMB_DEF (character to display the
relative position). Pass the desired characters as additional
parameters (for example, ListWindow(LW_MBAR_CHARS, &swd,
LW_MBAR_DEF, 254);).
The following messages can be returned by ListWindow:
LW_NULL_ARRAY - no item array has been defined.
LW_OK - the requested action has been performed.
LW_EXIT_KEY - an exit key has been pressed.
SCL1 Version 3.1 - Reference Manual - Page 145
ListWindow
LW_MOUSE_EVENT - the mouse has been clicked but it has not
been pointed to the area defined by the function.
LW_BUFFER_END - you have requested to move the cursor passed
the last item.
LW_BUFFER_BEGIN - you have requested to move the cursor up
passed the first active item.
LW_ILLEGAL_KEY - a key that undefined has been pressed.
LW_ILLEGAL_POSITION - you have requested to move the cursor
to an invalid position.
LW_NEW_POSITION - the cursor position has been updated.
LW_MOUSE_SELECT - one of the elements have been selected by
double clicking the mouse.
LW_MY_MOUSE - response to a LW_CHECK_MOUSE message if the
mouse has been clicked after pointing to the field area
defined by the function.
LW_NEW_MOUSEPOS - you have moved the cursor by clicking the
mouse after pointing to an item.
LW_BLOCK_MARK - you have tagged a group of items using your
mouse.
Example:
#include <scl1.h>
#include <scl1clor.h>
/* ListWindow example */
char *Items[]={ /* Array of items to display */
"11111",
"22222",
"33333",
"44444",
"55555",
"66666",
"77777",
"88888",
"99999",
"00000",
0, /* terminated with a "0" */
};
char TagA[10];
SCL1 Version 3.1 - Reference Manual - Page 146
ListWindow - LW_MoveTo - SW_MoveTo
main()
{
int EMess;
LWData lw; /* set lw as type LWData */
Cls(7,CLS_ALL);
ListWindow(LW_INIT,&lw);
lw.UpperRow=5; /* Set window size */
lw.LowerRow=9;
lw.LeftCol=20;
lw.RightCol=34;
lw.RColor=WHITE_BLACK+HIGHLIGHT;
lw.TagArray=TagA; /* tag array */
lw.Array=Items; /* data */
ListWindow(LW_DRAW,&lw); /* draw */
InitMouse(IM_SHOW);
do
{
EMess=ListWindow(LW_ACTIVE,&lw);
if(EMess==LW_ILLEGAL_KEY)
LW_MoveTo(&lw);
}while(EMess != LW_EXIT_KEY);
}
-----------------------------------------------------------------
LW_MoveTo, SW_MoveTo
-----------------------------------------------------------------
Purpose: These functions are used with ListWindow (LW_MoveTo)
and ScrollWindow (SW_MoveTo). When ListWindow and
ScrollWindow return an illegal key message, these
functions permit you to move the cursor position to
first item that starts with the Ascii character of
the key pressed.
Prototype: int LW_MoveTo(LWData *lwd);
int SW_MoveTo(SWData *sw);
Returns: Returns the position where the first item that
matches the key pressed is located.
Parameters: Each function requires you to specify a pointer to
the corresponding structure, LWData for List and
SWData for ScrollWindow.
Example: See ListWindow and ScrollWindow
SCL1 Version 3.1 - Reference Manual - Page 147
MCR_CloseFile - MCR_Init
-----------------------------------------------------------------
MCR_CloseFile
-----------------------------------------------------------------
Purpose: Closes a macro file.
Prototype: int MCR_CloseFile(void);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters: None
Example: See MCR_Init
-----------------------------------------------------------------
MCR_Init
-----------------------------------------------------------------
Purpose: Initialize or start the macro handling process.
Prototype: void MCR_Init(unsigned int Key,int (* userf)
(int flag,MACROData *md));
Returns: Nothing.
Parameters:
Key - the key that will be used to start or stop the macro
definition process (unsigned integer).
userf - pointer to a function that will be called when the
user selects to start or stop the macro recording process.
The user function receives two parameters, an action message
(flag) and a pointer to a MACROData structure. The following
messages are defined:
MACRO_START - The first time the key defined to record
macros (the Key parameter) is pressed, the user function
receives a MACRO_START message. The user function must
specify the structure that will be assigned to the macro,
the buffer to store the keystrokes and the maximum size.
The size shall be one integer (two bytes) larger than the
maximum macro size. All this information is included in
the MACROData structure.
SCL1 Version 3.1 - Reference Manual - Page 148
MCR_Init
MACRO_STOP - The next time the key defined to start/stop
macros is pressed, the function receives a MACRO_STOP
message. This instructs your user function that the macro
has been recorded. The actual macro size will be stored
in the "size" parameter of the MACROData structure.
Your user function can also receive the MACRO_REPORT or
NO_MACRO messages from the MCR_Report function. The user
function must check these messages and act accordingly.
(Please refer to the MCR_Report function).
The user function must return a value of "0" to indicate
the calling function that no problems have been found in
the macro handling process. If the user function returns
a "-1" the macro will not be recorded.
The macro information is stored in a structure type MACROData as
follows:
typedef struct{
unsigned int key; key to trigger or invoke the macro.
unsigned int size; Maximum number of keys to accept for
the macro (the macro size).
unsigned int *buffer; Pointer to the buffer that will hold
the macro, this buffer must be able to
store one character more than the
desired number of keys.
}MACROData;
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <malloc.h>
struct ErrorMess em[]={/* Messages for problems creating macros*/
1000,"The selected key is\nalready in use.",
1001,"Error creating macro file",
0};
macrof(int mess,MACROData *md); /* User defined macro processing
function */
main()
{
LEData led; /* A LineEditor will be used to get keys */
char buffer[81]; /* Buffer for storing keys */
SCL1 Version 3.1 - Reference Manual - Page 149
MCR_Init
Cls(7,CLS_ALL);
InitUserError(em);
memset(buffer,0,sizeof(buffer));
LineEditor(LE_INIT,&led); /* Line Editor initialization */
led.Buffer=buffer;
led.Prompt="Press F10 to define a macro";
led.FRow=1;
led.FLength=80;
led.FSize=80;
LineEditor(LE_DRAW,&led);
/* initialize macros, the parameters needed are: key to
start/stop the macro definition and the user defined function
that will be called */
MCR_Init(F10,macrof);
/* Read any macros that might have been stored in file KEYB.MCR*/
MCR_ReadFile("KEYB.MCR");
/* Activate Line Editor until an Exit Key is pressed */
while(LineEditor(LE_ACTIVE,&led) != LE_EXIT_KEY);
/* Before leaving, scan memory for macro functions and report
them to the user defined macro handling function*/
MCR_Report();
}
/* This is the user defined macro handling function, it is
called each time a macro recording is started or stopped and
by MCR_Report */
macrof(int mess,MACROData *md)
{
unsigned int key;
switch(mess) /* The parameter received is a message from the
macro function */
{
case MACRO_START:
/* The key defined for starting/stopping the macro recording
process has been pressed for the first time */
/* Place a message on the screen */
MessageOn(0x70,"Enter Macro key...\nPress F10 to end
macro");
SCL1 Version 3.1 - Reference Manual - Page 150
MCR_Init
do
{
key=GetKey();
/* Check if the key is already in use. MCR_MacroExist
returns "1" if that key is already in use */
if(key==F10 || MCR_MacroExist(key))
ErrorBox(1000);
else
break;
}while(1);
/* The MACROData structure holds the macro
information, its elements are:
key - key to trigger macro.
buffer - pointer to the buffer to store keys
(max keys + 1)
size - max number of keys to accept */
md->key=key; /* Save key into structure */
/* Allocate memory */
md->buffer=(unsigned int *)calloc(100,sizeof(int));
if(md->buffer==0)
mess=-1; /* do not record macro */
else
{
mess=0; /* OK record macro */
md->size=99; /* set an initial size /
}
MessageOff();
break;
case MACRO_STOP:
/* The key defined for starting/stopping the macro recording
process has been pressed for the second time */
md->size = the number of key pressed + 1
use this to resize allocated buffer */
MessageOn(7,"MACRO RECORDED");
WaitTime(100);
MessageOff();
SCL1 Version 3.1 - Reference Manual - Page 151
MCR_Init
md->buffer=realloc(md->buffer,md->size * sizeof(unsigned
int));
mess=0;
break;
case MACRO_REPORT:
MCR_Init - MCR_MacroEnable - MCR_MacroDisable
/* We have asked for a macro report (call MCR_Report
function). Macros will be reported one by one. md holds the
macro info*/
if(MCR_SaveMacro("KEYB.MCR",md)) /* Start saving macros
to disk file
KEYB.MCR */
{
ErrorBox(1001);
mess=-1;
}
else
mess=0;
break;
case MACRO_NO_MACRO:
/* MCR_Report indicates that no more macros could be found
*/
if(MCR_CloseFile())
ErrorBox(1001);
mess=0;
break;
}
return(mess);
}
SCL1 Version 3.1 - Reference Manual - Page 152
MCR_MacroEnable - MCR_MacroDisable - MCR_MacroExist
-----------------------------------------------------------------
MCR_MacroEnable, MCR_MacroDisable
-----------------------------------------------------------------
Purpose: These functions permit the programmer to enable or
disable the macro capabilities. They are useful if
you want to temporarily disable the keyboard macro
trapping while a routine waits for keyboard input,
etc.
Prototype: void MCR_MacroDisable(void);
void MCR_MacroEnable(void);
Returns: Nothing.
Parameters: None
-----------------------------------------------------------------
MCR_MacroExist
-----------------------------------------------------------------
Purpose: This function verifies if a given keyboard
combination has been previously assigned to a macro.
Prototype: int MacroExist(unsigned int Key);
Returns: Returns "0" if the key has not been assigned to a
macro or "1" if that key has been assigned.
Parameter: Key - Key to be verified if a macro has already been
assigned (unsigned integer), refer to file
SCL1KEYS.H.
Example: See MCR_Init
SCL1 Version 3.1 - Reference Manual - Page 153
MCR_Play - MCR_ReadFile
-----------------------------------------------------------------
MCR_Play
-----------------------------------------------------------------
Purpose: This function permits you to play a macro definition.
Prototype: void MCR_Play(unsigned int *macro);
Returns: Nothing
Parameter: macro - pointer to a macro defined as a null
terminated array of scan/ascii codes of the keys.
Example:
#include <scl1.h>
#include <scl1keys.h>
/* macro defined as a null terminated array of key scan codes */
unsigned int macro1[]={0x1e61,0x3062,0x2e63,0x2064,0};
MCR_Play(macro1); /* ask macro func. to play macro1 */
-----------------------------------------------------------------
MCR_ReadFile
-----------------------------------------------------------------
Purpose: Opens a file for retrieving macros.
Prototype: int MCR_ReadFile(char *FileName);
Returns: The DOS error code, "0" if no error occurs or "255"
if there is not enough memory to retrieve the macros
from the file. (See Appendix "A", for more
information).
Parameter: FileName - char pointer to the filename to be used
for storing or retrieving macros.
Example: See MCR_Init
SCL1 Version 3.1 - Reference Manual - Page 154
MCR_Record - MCR_RegisterBackF
-----------------------------------------------------------------
MCR_Record
-----------------------------------------------------------------
Purpose: This function permits you to start a macro
definition. It offers an alternative to start macro
recording without the use of a hot key, like from a
menu.
Prototype: void MCR_Record(void);
Returns: Nothing
Parameters: None
-----------------------------------------------------------------
MCR_RegisterBackF
-----------------------------------------------------------------
Purpose: This function permits your program to trap a given
key. The function checks if the key has been pressed
each time there is keyboard activity, and when it
detects that it has been pressed it calls a user
function defined as a parameter.
Prototype: void MCR_RegisterBackF(void(*userf)(void));
Returns: Nothing
Parameter: userf - pointer to an user defined function that will
be called in the background when no keys are being
processed.
SCL1 Version 3.1 - Reference Manual - Page 155
MCR_RegisterMacro
-----------------------------------------------------------------
MCR_RegisterMacro
-----------------------------------------------------------------
Purpose: This function permits to add a macro. This function
provides an alternate way to add macros to memory.
Prototype: int MCR_RegisterMacro(unsigned int Key,
unsigned int size,unsigned int *Buffer);
Returns: Returns "0" if the macro has been successfully
defined or "1" if there is not sufficient memory to
store the macro.
Parameters:
key - the key to trigger or invoke the macro (unsigned
integer).
size - the maximum number of keys to accept for the macro
(unsigned integer).
buffer - pointer to the buffer that will hold the macro, this
buffer must be able to store one character more than the
desired number of keys (unsigned integer).
Example:
unsigned int Macrobuf[]={'M','a','c','r','o',0};
MCR_RegisterMacro(CTRLF1,sizeof(Macrobuf),Macrobuf);
SCL1 Version 3.1 - Reference Manual - Page 156
MCR_RegisterTrapKey - MCR_Report
-----------------------------------------------------------------
MCR_RegisterTrapKey
-----------------------------------------------------------------
Purpose: This function permits your program to trap a given
key. The function checks if the key has been pressed
each time there is keyboard activity, and when it
detects that it has been pressed it calls a user
function defined as a parameter.
Prototype: int MCR_RegisterTrapKey(unsigned int Key,
int (* userf)());
Returns: Returns "0" if the key has been successfully trapped
or "1" if there is not enough memory available to
store the information.
Parameters:
Key - Key to be trapped (unsigned integer), most keys have
been defined in header file SCL1KEYS.H.
userf - pointer to an user defined function that will be
called every time the trapped key is pressed.
-----------------------------------------------------------------
MCR_Report
-----------------------------------------------------------------
Purpose: Scans the memory for defined macros and reports the
macros found to the function that is processing the
macros. Sends a message to the macro user function a
MACRO_REPORT message each time it finds a macro or
MACRO_NO_MACRO when it does not finds any more
macros. Your user function can use this messages to
manage the macros. See example.
Prototype: void ReportMacro(void);
Returns: Nothing
Parameters: None
Example: See MCR_Init
SCL1 Version 3.1 - Reference Manual - Page 157
MCR_SaveMacro
-----------------------------------------------------------------
MCR_SaveMacro
-----------------------------------------------------------------
Purpose: Opens a file, if not open, and saves a macro in
memory to the file.
Prototype: int MCR_SaveMacro(char *FileName,MACROData *md);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters: The macro data information is given in a structure
type MACROData as follows:
Structure type MACROData;
typedef struct{
unsigned int key; Key to trigger or invoke the macro.
unsigned int size; Maximum number of keys to accept for
the macro.
unsigned int *buffer; Pointer to the buffer that will hold
the macro, this buffer must be able to
store one character more than the
desired number of keys.
}MACROData;
The parameters passed to the function are:
FileName - pointer to the filename to be used for storing or
retrieving macros (char).
md - pointer to the MACROData structure.
Example: See MCR_Init
SCL1 Version 3.1 - Reference Manual - Page 158
MCR_UnregisterBackF - MCR_UnregisterMacro - MCR_UnregisterTrapKey
-----------------------------------------------------------------
MCR_UnregisterBackF
-----------------------------------------------------------------
Purpose: This function permits your program to release a
background function previously defined using the
MCR_RegisterBackF function.
Prototype: void MCR_UnregisterBackF(void);
Returns: Nothing.
Parameters: None
-----------------------------------------------------------------
MCR_UnregisterMacro
-----------------------------------------------------------------
Purpose: This function permits to remove a previously defined
macro.
Prototype: unsigned int *MCR_UnregisterMacro(unsigned int Key);
Returns: Returns a pointer the macro buffer.
Parameter: key - key assigned to trigger or invoke the macro
(unsigned int).
-----------------------------------------------------------------
MCR_UnregisterTrapKey
-----------------------------------------------------------------
Purpose: This function permits your program release trapping
of a given key. The key must have been previously
trapped using the MCR_RegisterTrapKey function.
Prototype: void MCR_UnregisterTrapKey(unsigned int Key);
Returns: Nothing.
Parameter: Key - Key that has been previously trapped (unsigned
int).
SCL1 Version 3.1 - Reference Manual - Page 159
MakeDir
-----------------------------------------------------------------
MakeDir
-----------------------------------------------------------------
Purpose: Creates a new directory.
Prototype: int MakeDir(char *Path);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: Path - char pointer to a string holding the new
directory name.
Example:
#include <scl1.h>
char Dir[]="SCL1";
main()
{
int i;
printf("\nCreating SCL1 directory...\n");
i=MakeDir(Dir);
if(i)
{
printf("\nUnable to create directory\n");
exit(-1);
}
else
printf("SCL1 directory has been created.\n");
printf("\nDeleting SCL1 directory...\n");
i=RemoveDir(Dir);
if(i)
printf("\nUnable to remove directory\n");
else
printf("SCL1 directory has been deleted.\n");
}
SCL1 Version 3.1 - Reference Manual - Page 160
Menu - MouseMenu - MouseMenu2
-----------------------------------------------------------------
Menu, MouseMenu, MouseMenu2
-----------------------------------------------------------------
Purpose: Displays a scrolling or moving bar type menu. A
selection is made by either pressing the highlighted
menu option letter or by scrolling the highlighted
bar using the arrow keys and then pressing the ENTER
key. With MouseMenu you can also make a selection by
moving the mouse cursor to the desired line and
clicking the left mouse button. MouseMenu2 is
identical to MouseMenu but will let you specify a
default selection.
Prototype: int Menu(int NColor,int RColor,int HColor,int NumOpt,
struct MenuOpt *mo);
int MouseMenu(int NColor,int RColor,int HColor,
int NumOpt,struct MenuOpt *k,int XMin,int XMax,
int YMin,int YMax);
int MouseMenu2(int NColor,int RColor,int HColor,
int NumOpt,struct MenuOpt *mo,int XMin,int XMax,
int YMin,int YMax,int StartSel);
Returns: The selection number (>0) or -1 if ESC is pressed.
Parameters: The menu information must be entered as an array of
structures as follows; with one array element for
each menu option:
struct MenuOpt{
int Row; Row position for the menu item.
int Col; Column position for the menu item.
char *String; Pointer to the menu item text.
char Letter; Letter to be highlighted for fast keyboard
selection of the menu item.
};
The parameters passed to the function are:
NColor - color for the menu background and foreground (int).
RColor - color for the highlighted item menu bar (integer).
HColor - color for the highlighted quick selection menu item
letter (integer).
SCL1 Version 3.1 - Reference Manual - Page 161
Menu - MouseMenu - MouseMenu2
NumOpt - number of menu options (integer).
MenuOpt - pointer to the menu structure previously defined.
For MouseMenu only;
XMin - minimum row position of menu area (integer).
XMax - maximum row position of menu area (integer).
YMin - minimum column position of menu area (integer).
YMax - maximum column position of menu area (integer).
For MouseMenu2 only;
StartSel - default selection (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
/* Shows the use of Menu, MouseMenu and MouseMenu2 */
struct MenuOpt Mainm[7]={/*Array of structures with 7 elements */
5,26,"Screen Related Functions ",'S', /* First option */
7,26,"Keyboard Handling Functions ",'K', /* Second option */
9,26,"Mouse Handling Functions ",'M', /* Third option */
11,26,"Program Flow Functions ",'P',/* Fourth option */
13,26,"File Handling Functions ",'F',/* Fifth option */
15,26,"Background and Miscellaneous",'B',/* Sixth option */
17,26,"Exit Demo ",'E',/* Seventh option */
};
main()
{
int Selection;
Cls(WHITE_BLACK,CLS_ALL);
Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */
WriteScreen(WHITE_BLACK,3,38,"MENU"); /* Menu title */
/* Menu */
Selection=Menu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,7,
Mainm);
Cls(WHITE_BLACK,CLS_ALL);
SCL1 Version 3.1 - Reference Manual - Page 162
Menu - MouseMenu - MouseMenu2
if(Selection > 0)
printf("You have selected option %i, press any key...\n",
Selection);
else
printf("You have pressed ESCAPE, press any key...\n");
GetKey();
InitMouse(IM_SHOW);
/* MouseMenu */
Cls(WHITE_BLACK,CLS_ALL);
Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */
WriteScreen(WHITE_BLACK,3,35,"MOUSE MENU"); /* Menu title */
Selection=MouseMenu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+
HIGHLIGHT,7,Mainm,24,55,3,18);
Cls(WHITE_BLACK,CLS_ALL);
if(Selection > 0)
printf("You have selected option %i\n",Selection);
else
printf("You have pressed ESCAPE or clicked the mouse outside
the menu area.\n");
WaitKeyMouse();
/* MouseMenu2 - with MouseMenu2 you can select the option that
will be active when the menu first appears (last parameter)*/
Cls(WHITE_BLACK,CLS_ALL);
Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */
WriteScreen(WHITE_BLACK,3,35,"MOUSE MENU2 ");/* Menu title */
Selection=MouseMenu2(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+
HIGHLIGHT,7,Mainm,24,55,3,18,3);
Cls(WHITE_BLACK,CLS_ALL);
if(Selection > 0)
printf("You have selected option %i\n",Selection);
else
printf("You have pressed ESCAPE or clicked the mouse outside
the menu area.\n");
}
SCL1 Version 3.1 - Reference Manual - Page 163
MenuSystem - MenuSystem2
-----------------------------------------------------------------
MenuSystem, MenuSystem2
-----------------------------------------------------------------
Purpose: Displays a pull-down menu system. The function
requires to define various structures and data
blocks. MenuSystem2 is identical to MenuSystem
except that it provides the capability to display a
text string associated with each menu option and of
"greying" out options (making options unavailable
under certain conditions).
Prototype: int MenuSystem(int Message,MSData *msd,...);
int MenuSystem2(int Message,MSData2 *msd,...);
Returns: This are dialog type functions. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The information is given as follows:
1. The top row menu information is defined as an array of
structures type MSBar (for MenuSystem) or MSBar2 (for
MenuSystem2) as follows, one element for each of the main
options:
typedef struct{
int StartCol; Column position of the first character
of the option's prompt.
int EndCol; Column position of the last character
of the option's prompt.
unsigned int Key; Key (or combination) that will be used
to call the pull-down menu. (Necessary
when using keyboard input).
char *String; Pointer to a string containing the
option's prompt.
}MSBar;
Notes:
A. The MSBar and MSBar2 structures are identical. Two
different names have been used to prevent confusion.
B. The StartCol and EndCol information is used to determine
the mouse range for that option and to highlight it when
selected. For proper operation make sure that options do
not overlap.
SCL1 Version 3.1 - Reference Manual - Page 164
MenuSystem - MenuSystem2
2. Each pull-down menu is defined as an array of structures type
MSOptions (for MenuSystem) or MSOptions2 (for MenuSystem2).
The structure is similar to that used for the Menu function:
typedef struct{
int Row; Row position for the menu item.
int Col; Column position for the menu item.
char *String; Pointer to the menu item text.
char Letter; Letter to be highlighted for fast
keyboard selection of the menu item.
}MSOptions;
typedef struct{
int Row; Row position for the menu item.
int Col; Column position for the menu item.
char *String; Pointer to the menu item text.
char Letter; Letter to be highlighted for fast
keyboard selection of the menu item.
int Active; Status of the option. "1" makes the
option available and a "0"
unavailable.
char *Text; Pointer to a text string that will be
displayed when the corresponding menu
option is highlighted.
}MSOptions2;
3. The pull down menu box information is defined in a structure
type MSWindows (for MenuSystem) or MSWindow2 (for
MenuSystem2), as an array of structures for the menu system,
one element for each pull-down menu as follows:
typedef struct{
int UpperRow; Upper row position of the box used to
enclose the pull-down menu.
int LeftCol; Left column position of the box.
int LowerRow; Lower row position of the box.
int RightCol; Right column position of the box.
SCL1 Version 3.1 - Reference Manual - Page 165
MenuSystem - MenuSystem2
int Number; Number of options in the pull-down
menu.
char *WinBuffer; Buffer to store the screen area, used
when popping out the pull-down menu.
MSOptions *mso; Pointer to the MSOptions structure
corresponding to that pull-down menu.
}MSWindow;
typedef struct{
int UpperRow; Refer to the MSWindow structure
int LeftCol; " "
int LowerRow; " "
int RightCol; " "
int Number; " "
char *WinBuffer; " "
MSOptions2 *mso; Pointer to the MSOptions2 structure
corresponding to that pull-down menu.
}MSWindow2;
4. The remaining information is defined in a structure type
MSData (for MenuSystem) or MSData2 (for MenuSystem2) as
follows:
typedef struct{
int BarNColor; Normal color for top row or bar
menu.
int BarRColor; Reversed color for top row menu.
int MenuNColor; Normal color for the pull-down
menus.
int MenuRColor; Reversed color for the pull-down
menus.
int MenuHColor; Highlight color for hot-keys.
MSBar *msb; Pointer to the MSBar structure.
MSWindow *msw; Pointer to the MSWindow
structure.
int Number; Number of pull-down menus in the
system.
SCL1 Version 3.1 - Reference Manual - Page 166
MenuSystem - MenuSystem2
int Menu; Holds the active pull-down menu
number.
int Option; Holds the active option of the
selected pull-down menu.
unsigned int EventInfo; Event information for the Menu
System.
}MSData;
typedef struct{ Refer to the MSData structure
int BarNColor; " "
int BarRColor; " "
int MenuNColor; " "
int MenuRColor; " "
int MenuHColor; " "
int MenuGNColor; Normal color for the "grayed"
(unavailable) out menu options.
int MenuGRColor; Reversed color for the "grayed"
out menu options.
MSBar2 *msb; Pointer to the MSBar2 structure.
MSWindow2 *msw; Pointer to the MSWindow2
structure.
int Number; Refer to the MSData structure
int Menu; " "
int Option; " "
unsigned int EventInfo; " "
int TextColor; Color to be used for displaying
the text related to menu option.
int TextRow; Row position for displaying the
text.
int TextCol; Column position for displaying
the text.
int TextLength; Length of the text
}MSData2;
SCL1 Version 3.1 - Reference Manual - Page 167
MenuSystem - MenuSystem2
Messages:
The following messages can be sent to MenuSystem and MenuSystem2:
MS_INIT - initialize the MSData structure to NULL and set the
following values as follows:
BarNColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
BarRColor - set to white characters in a black background
or the normal color set by SetDialogColors.
MenuNColor - set to white characters in a black
background or the normal color set by SetDialogColors.
MenuRColor - set to black characters in a white
background or the reversed color set by SetDialogColors.
MenuHColor - set to highlighted white characters in a
black background or the highlight color set by
SetDialogColors.
MS_DRAW - draw the bar menu.
MS_CHECK - checks if any key or mouse event related to the
MenuSystem has been activated in which case it will retain
control and respond to the following keys:
Key Action
Up Arrow cursor to previous option.
Down Arrow cursor to next option.
Left Arrow select previous pull-down menu.
Right Arrow select next pull-down menu.
MS_KEY - the parameter passed with this message (Scan+Ascii
code of the key) is a control key value that performs as if
the control key has been pressed.
MS_SHADOW_ON - turn on a shadow effect for pull-down menus.
Make sure to set enough space for the shadow characters in
the MSWindows structure.
MS_SHADOW_OFF - turn off shadow effect on pull-down menus.
MS_LINE_ON - draw horizontal lines on empty spaces inside a
menu box.
SCL1 Version 3.1 - Reference Manual - Page 168
MenuSystem - MenuSystem2
MS_LINE_OFF - do not draw horizontal lines on empty spaces in
menu box (default).
MS_SET_FRAME_TYPE - sets the frame type for pull down menus
to the type specified with an additional parameter (default
is single line).
MS_SET_BAR_ROW - set the row position where to display the
bar menu to the value specified with an additional parameter
(default is "0").
MS_SET_BAR_START - sets the column position where the bar
menu starts to the value specified with an additional
parameter (default is "0").
MS_SET_BAR_END - sets the column position where the bar menu
ends to the value specified with an additional parameter
(default is the maximum screen width).
MS_SHOW_MENU - enable the display of the menu system.
MS_HIDE_MENU - disable the display of the menu system.
MS_ALT_ON - set ALT key to bring down pull-down menus.
MS_ALT_OFF - disable the ALT key to bring pull-down menus.
MS_SET_FRAME_COLOR - set the pull-down menu box's frame
color, if this message is not sent it is set to normal color.
MS_RESET_FRAME_COLOR - reset the pull-down menu box's frame
to normal color.
MS_RESET - reset the menu system to the default values.
The following messages can be returned by MenuSystem and
MenuSystem2:
MS_NO_SELECT - no selection has been made.
MS_OK - action requested has been successfully performed.
MS_SELECT - a selection has been made. This means that the
structure element containing the selection information must
be checked to determine what has been the selection.
MS_CANCEL - the mouse has been clicked after pointing outside
the window area or the "ESC" key has been pressed.
SCL1 Version 3.1 - Reference Manual - Page 169
MenuSystem - MenuSystem2
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
/* MenuSystem example */
MSBar msb[]={
/* Menu-bar data:
Start and end column of each option
Menu's key SCAN-ASCII code
String */
1,6,0x2100," File ",
7,12,0x1200," Edit ",
};
/* first pull-down menu
row, column position
string
hot-key */
MSOptions mso0[]={
2,1," Load ",'L',
3,1," Save ",'S',
4,1," Quit ",'Q',
};
/* second pull-down menu */
MSOptions mso1[]={
2,7," Mark ",'M',
3,7," Cut ",'C',
4,7," Copy ",'y',
5,7," Paste ",'P',
};
/* buffer for storing pull down menu screen area */
char WindowBuf[140];
/* Pull-down menu box & window information
top left corner and bottom right corner positions
number of options
buffer for saving screen area
MSOptions structure */
SCL1 Version 3.1 - Reference Manual - Page 170
MenuSystem - MenuSystem2
MSWindow msw[]={
1,0,5,7,3,WindowBuf,mso0,
1,6,6,14,4,WindowBuf,mso1,
};
/* This structure links all previous structures */
MSData msd=
{
/* bar-menu colors */
BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
/* pull-down menu colors */
WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
/* MSBar, MSWindow structures, number of menus and internal
variables */
msb,msw,2,0,0,0};
main()
{
int Mess;
InitMouse(IM_SHOW); /* initialize mouse */
/* Draw shadows */
MenuSystem(MS_SHADOW_ON,(MSData *)0);
/* MenuSystem will be ALT sensitive */
MenuSystem(MS_ALT_ON,(MSData *)0);
/* draw */
MenuSystem(MS_DRAW,&msd);
do
{
/* a key pressed? */
if(Mess=KeyReady())
{
SCL1 Version 3.1 - Reference Manual - Page 171
MenuSystem - MenuSystem2
/* send key to MenuSystem */
Mess=MenuSystem(MS_KEY,&msd,Mess);
/* If we still have a key it means it was not a MenuSystem
key, discard key. If your program needs to service the
keyboard you should do it here. */
if(KeyReady())
GetKey();
}
else
/* Let MenuSystem check if the mouse has been clicked or a
selection has been made */
Mess=MenuSystem(MS_CHECK,&msd);
if(Mess==MS_SELECT)
{
/* a selection was made, msd.Menu=selected menu */
switch(msd.Menu)
{
case 1:
/* first menu, msd.Option=selected option */
switch(msd.Option)
{
case 1:
/* first option */
MessageOn(BLACK_WHITE,"Load");
WaitTime(100);
MessageOff();break;
case 2:
/* second option */
MessageOn(BLACK_WHITE,"Save");
WaitTime(100);
MessageOff();break;
case 3:
/* third option */
MessageOn(BLACK_WHITE,"Quit");
WaitTime(100);
SCL1 Version 3.1 - Reference Manual - Page 172
MenuSystem - MenuSystem2
MessageOff();
break;
}
break;
case 2:
/* second menu */
switch(msd.Option)
{
case 1:
/* first option */
MessageOn(BLACK_WHITE,"Mark");
WaitTime(100);
MessageOff();
break;
case 2:
/* second option */
MessageOn(BLACK_WHITE,"Cut");
WaitTime(100);
MessageOff();
break;
case 3:
/* third option */
MessageOn(BLACK_WHITE,"Copy");
WaitTime(100);
MessageOff();
break;
case 4:
/* fourth option */
MessageOn(BLACK_WHITE,"Paste");
WaitTime(100);
MessageOff();
break;
}
break;
}
}
}while(msd.Menu != 1 || msd.Option != 3);
}
SCL1 Version 3.1 - Reference Manual - Page 173
MenuSystem - MenuSystem2
/****************************************************************
MenuSystem2 example. You can display a help-line and grayed-out
menu items with MenuSystem2 */
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
MSBar2 msb[]={
/* Menu-bar data:
Start and end column of each option
Menu's key SCAN-ASCII code
String */
1,6,0x2100," File ",
7,12,0x1200," Edit ",
};
/* first pull-down menu
row, column position
string
hot-key
1=active,0=inactive option
help text */
MSOptions2 mso0[]={
2,1," Load ",'L',1,"Load new file",
3,1," Save ",'S',0,"Save edited file", /* inactive option*/
4,1," Quit ",'Q',1,"Exit to DOS",
};
/* second pull-down menu */
MSOptions2 mso1[]={
2,7," Mark ",'M',1,"Mark block",
3,7," Cut ",'C',1,"Cut text block",
4,7," Copy ",'y',1,"Copy text block",
5,7," Paste ",'P',1,"Paste text block",
};
/* buffer for storing pull down menu screen area */
char WindowBuf[140];
/* Pull-down menu box & window information
top left corner and bottom right corner positions
number of options
buffer for saving screen area
MSOptions structure */
SCL1 Version 3.1 - Reference Manual - Page 174
MenuSystem - MenuSystem2
MSWindow2 msw[]={
1,0,5,7,3,WindowBuf,mso0,
1,6,6,14,4,WindowBuf,mso1,
};
/* This structure links all previous structures */
MSData2 msd=
{
/* bar-menu colors */
BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
/* pull-down menu colors */
WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,
/* normal and reverse color for inactive options */
BLACK_BLACK+HIGHLIGHT,BLACK_WHITE+HIGHLIGHT,
/* MSBar, MSWindow structures, number of menus and internal
variables */
msb,msw,2,0,0,0,
/* text color, line, column, and length */
BLACK_WHITE,24,0,80};
main()
{
int Mess;
InitMouse(IM_SHOW); /* initialize mouse */
/* Draw shadows */
MenuSystem2(MS_SHADOW_ON,(MSData *)0);
/* MenuSystem2 will be ALT sensitive */
MenuSystem2(MS_ALT_ON,(MSData *)0);
/* draw */
MenuSystem2(MS_DRAW,&msd);
do
SCL1 Version 3.1 - Reference Manual - Page 175
MenuSystem - MenuSystem2
{
/* a key pressed? */
if(Mess=KeyReady())
{
/* send key to MenuSystem2 */
Mess=MenuSystem2(MS_KEY,&msd,Mess);
/* If we still have a key it means it was not a
MenuSystem2 key, discard key. If your program
needs to service the keyboard you should do it
here. */
if(KeyReady())
GetKey();
}
else
/* Let MenuSystem2 check if the mouse has been
clicked or a selection has been made */
Mess=MenuSystem2(MS_CHECK,&msd);
if(Mess==MS_SELECT)
{
/* a selection was made, msd.Menu=selected menu */
switch(msd.Menu)
{
case 1:
/* first menu, msd.Option=selected option */
switch(msd.Option)
{
case 1:
/* first option */
MessageOn(BLACK_WHITE,"Load");
WaitTime(100);
MessageOff();break;
SCL1 Version 3.1 - Reference Manual - Page 176
MenuSystem - MenuSystem2
case 2:
/* second option, since is inactive
we'll never receive this
selection*/
MessageOn(BLACK_WHITE,"Save");
WaitTime(100);
MessageOff();break;
case 3:
/* third option */
MessageOn(BLACK_WHITE,"Quit");
WaitTime(100);
MessageOff();
break;
}
break;
case 2:
/* second menu */
switch(msd.Option)
{
case 1:
/* first option */
MessageOn(BLACK_WHITE,"Mark");
WaitTime(100);
MessageOff();
break;
case 2:
/* second option */
MessageOn(BLACK_WHITE,"Cut");
WaitTime(100);
MessageOff();
break;
case 3:
/* third option */
MessageOn(BLACK_WHITE,"Copy");
WaitTime(100);
MessageOff();
break;
SCL1 Version 3.1 - Reference Manual - Page 177
MenuSystem - MenuSystem2 - MESS_SetPosition
case 4:
/* fourth option */
MessageOn(BLACK_WHITE,"Paste");
WaitTime(100);
MessageOff();
break;
}
break;
}
}
}while(msd.Menu != 1 || msd.Option != 3);
}
-----------------------------------------------------------------
MESS_SetPosition
-----------------------------------------------------------------
Purpose: Permits changing the position of a MessageOn/Off
display to any place in the screen.
Prototype: void MESS_SetPosition(int UpperRow,int LeftCol);
Returns: Nothing
Parameters:
UpperRow - upper row position of the Message box (integer).
LeftCol - left column position of the Message box (integer).
Example: See MessageShadowOn/Off
SCL1 Version 3.1 - Reference Manual - Page 178
MessageOff
-----------------------------------------------------------------
MessageOff
-----------------------------------------------------------------
Purpose: Removes the message box displayed by MessageOn and
restores the screen's previous contents.
Prototype: void MessageOff(void);
Returns: Nothing
Parameters: None
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
int i;
char buffer[8];
memset(buffer,0,sizeof(buffer));
/* display message */
MessageOn(WHITE_BLACK,"Counting to 30,000...");
for(i=0;i < 30000; i++) /* loop */
/* write inside MessageOn screen area */
WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer));
MessageOff(); /* restore screen */
}
See also MessageOn, MessageShadowOff and MessageShadowOn.
SCL1 Version 3.1 - Reference Manual - Page 179
MessageOn - MessageShadowOff - MessageShadowOn
-----------------------------------------------------------------
MessageOn
-----------------------------------------------------------------
Purpose: Displays a message inside a box in the center of the
screen. The screen area is saved and is restored when
MessageOff is called.
Prototype: void MessageOn(int Color, char *String);
Returns: Nothing
Parameters:
Color - Box/message color (integer).
String - pointer to string.
Note: Messages are written inside a box. They can have up to 5
lines with up to 40 characters each. Use control
character '\n' to indicate new line. The box will stay on
the screen until MessageOff is called. Each line will be
centered in the window. Lines will also be centered
vertically. You can call MessageOn as many times as
desired without turning them off with MessageOff. Use
MessageOff to restore the screen with its original
contents before calling the MessageOn for the first time.
Example: See MessageOff
See also MessageOff, MessageShadowOff and MessageShadowOn.
-----------------------------------------------------------------
MessageShadowOff, MessageShadowOn
-----------------------------------------------------------------
Purpose: Displays or disable a shadow effect when using the
MessageOn/MessageOff functions. After any of these
functions are called subsequent calls to the
MessageOn function will be displayed with (or
without) a shadow effect.
Prototype: void MessageShadowOff(void);
void MessageShadowOn(void);
Returns: Nothing.
Parameters: None.
SCL1 Version 3.1 - Reference Manual - Page 180
MessageShadowOff - MessageShadowOn
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
int i;
/*Clear screen so that shadow effect can be seen */
Cls(BLACK_WHITE,CLS_ALL);
MESS_SetPosition(4,10);/*Place Message box in row 4, col 10 */
MessageOn(WHITE_BLUE,"MessageOn function without
shadow\nPress any key...");
GetKey();
MessageOff();
MessageShadowOn();
MessageOn(WHITE_BLUE,"MessageOn function WITH shadow
\nPress any key...");
GetKey();
MessageOff();
MessageShadowOff();
MessageOn(WHITE_BLUE,"MessageOn function again\nwithout
shadow\nPress any key...");
GetKey();
MessageOff();
}
See MessageOn and MessageOff.
SCL1 Version 3.1 - Reference Manual - Page 181
ModifyCharSet
-----------------------------------------------------------------
ModifyCharSet
-----------------------------------------------------------------
Purpose: Lets you redefine or modify one or more characters
when using VGA or EGA display adapters. The character
data is passed as a bitmap of 9 X 14 pixels (for
EGA), 9 X 16 pixels (for VGA) or 8 X 8 pixels (for
CGA). Once a character is redefined it can be
displayed using the ASCII code corresponding to that
character.
You can convert small bitmapped drawings into a
series of consecutive characters using the included
BMPCNV.C utility program. The drawing must be saved
using the Windows 3.0 BMP format. To use the utility
program you must first compile and link it. The
comments on the file explain its usage. This program
may also help to explain how to use the character set
functions. See Appendix "J".
Prototype: void ModifyCharSet(int Points,int StartCode,
int TotalChars,char *Bits);
Returns: Nothing
Parameters:
Points - number of scan lines used for the character as per
the following table (integer):
MODE POINTS
80 x 25 16
VGA 80 x 28 14
80 x 50 8
EGA 80 x 25 14
80 x 43 8
StartCode - ASCII code of the first character to modify
(integer).
TotalChars - number of characters to modify (integer).
Bits - pointer to an array that contain a bitmap of the
character definition.
SCL1 Version 3.1 - Reference Manual - Page 182
ModifyCharSet
Example:
#include <scl1.h>
/* This file shows the use of GetCharSet and ModifyCharSet to
modify VGA and EGA character definition tables */
/* copyright symbol for the VGA */
char VGAcopyr[]={0x00,0x00,0x00,0x0f,0x18,0x33,0x26,0x26,0x26,
0x26,0x33,0x18,0x0f,0x00,0x00,0x00,0x00,0x00,
0x00,0xf8,0x0c,0xe6,0x22,0x02,0x02,0x22,0xe6,
0x0c,0xf8,0x00,0x00,0x00};
/* copyright symbol for the EGA */
char EGAcopyr[]={0x00,0x00,0x0f,0x18,0x33,0x26,0x26,0x26,0x26,
0x33,0x18,0x0f,0x00,0x00,0x00,0x00,0xf8,0x0c,
0xe6,0x22,0x02,0x02,0x22,0xe6,0x0c,0xf8,0x00,
0x00};
main()
{
unsigned char OldChar[32 * 2]; /* Buffer */
VideoConfig();
if(VC_Monitor != VC_VGA && VC_Monitor != VC_EGA)
{
printf("Your monitor does not support character
modification\n");
exit(-1);
}
/* We will change ASCII characters 192-193 into a copyright
symbol but first we'll copy the original characters so that
they can be restored later */
GetCharSet(192,2,OldChar);
/* Modify character definition */
if(VC_Monitor==VC_VGA)
ModifyCharSet(16,192,2,VGAcopyr);
else
ModifyCharSet(14,192,2,EGAcopyr);
SCL1 Version 3.1 - Reference Manual - Page 183
ModifyCharSet - ModifyPalette
/* Write the new copyright character */
printf("The new copyright symbol \xc0\xc1, press any key...\n");
WaitKeyMouse();
/* restore characters */
ModifyCharSet(32,192,2,OldChar);
printf("Symbols restored\n");
}
-----------------------------------------------------------------
ModifyPalette
-----------------------------------------------------------------
Purpose: Modify all palette colors. The color array contains
seventeen values, 16 colors and the screen border
color. See Appendix "J".
Prototype: void ModifyPalette(char *Colors);
Returns: Nothing
Parameters:
Colors - Char pointer to an array of new colors containing 17
values, 16 colors and the border color.
SCL1 Version 3.1 - Reference Manual - Page 184
ModifyPaletteColor
-----------------------------------------------------------------
ModifyPaletteColor
-----------------------------------------------------------------
Purpose: Modifies one palette entry. See Appendix "J".
Prototype: void ModifyPaletteColor(int Palette,int NewValue);
Returns: Nothing
Parameters:
Palette - palette number (integer).
NewValue - new color (integer).
Example:
#include <scl1.h>
#include <scl1keys.h>
/* This file shows how to use ModifyPaletteColor to change
palette settings in a VGA or EGA monitor */
static char PaldemoText1[]=" Up/Down arrow keys - modify
background color background color:\n"
"Left/Right arrow keys - modify
foreground color foreground color:";
static char PaldemoText2[]="ESC to\n EXIT";
main()
{
int bcolor=0,fcolor=7;
char buffer[12];
unsigned int key;
/* We Will modify palette entry 0 (normally black) and palette
entry 7 (white) */
InitVideo();
FillBlock(7,0,0,22,79,'X'); /* fill screen */
WriteScreen(7,23,0,PaldemoText1); /* write message */
WriteScreen(7,23,73,PaldemoText2);
do
{
SCL1 Version 3.1 - Reference Manual - Page 185
ModifyPaletteColor
/* write palette entry values */
sprintf(buffer,"0x%02x\n0x%02x",bcolor,fcolor);
WriteScreen(7,23,67,buffer);
switch((key=GetKey()))
{
case UP: /* let user modify value with keyboard */
if(bcolor < 63)
{
++bcolor;
ModifyPaletteColor(0,bcolor); /* modify palette */
}
break;
case DOWN:
if(bcolor > 0)
{
--bcolor;
ModifyPaletteColor(0,bcolor);
}
break;
case RIGHT:
if(fcolor < 63)
{
++fcolor;
ModifyPaletteColor(7,fcolor);
}
break;
case LEFT:
if(fcolor > 0)
{
--fcolor;
ModifyPaletteColor(7,fcolor);
}
break;
}
}while(key != ESC);
InitVideo(); /* restore to default */
}
SCL1 Version 3.1 - Reference Manual - Page 186
MouseButton
-----------------------------------------------------------------
MouseButton
-----------------------------------------------------------------
Purpose: A Mouse Button is a prompt that can be placed
anywhere in the screen, that when pointed and clicked
by the mouse performs a given action. It performs as
a sensitive screen prompt. The selected button is
drawn in the specified color with or without a box.
Most functions, like FileBox, use Mouse Buttons (to
select or cancel). If you require more than one Mouse
Button it is better to use Fields2.
Prototype: int MouseButton(int Message,MBData *p);
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The MouseButton information must be
given in a structure, type MBData, as follows:
typedef struct{
int NColor; Color used for an unselected
button.
int RColor; Color used for a selected button.
int UpperRow; Upper row position of the Button
area.
int LeftCol; Left column position of the Button
area.
int LowerRow; Lower row position of the Button
area.
int RightCol; Right column position of the Button
area.
int PRow; Row position of the Mouse Button
text.
int PCol; Column position of the Button text.
char *Prompt; Char pointer to the Mouse Button
text.
SCL1 Version 3.1 - Reference Manual - Page 187
MouseButton
int BoxFlag; Flag to indicate if a box shall be
drawn around a Mouse Button.
int ActiveFlag; Flag to indicate if the Button is
active.
unsigned int *ExitKeys; Array of keys to exit the function.
unsigned int EventInfo; Holds the key pressed when you exit
the function or a non defined key
is pressed.
}MBData;
Messages:
The following messages can be sent to MouseButton:
MB_INIT - initialize the MBData structure to NULL and set the
following default values:
NColor - white characters in a black background or the
normal color set by SetDialogColors.
RColor - black characters in a white background or the
reversed color set by SetDialogColors.
MB_DRAW - display the Mouse Button.
MB_ACTIVE - move the cursor to the Mouse Button. This
message is used by the Fields2 function.
MB_CHECK_MOUSE - check to see if the mouse has been clicked
after pointing to the Mouse Button.
MB_RESET - reset the Mouse Button variables to the default
values. If exit keys have not been defined, set to the
default exit keys.
The following messages can be returned by MouseButton:
MB_OK - the function has performed the requested action.
MB_EXIT_KEY - an exit key has been pressed.
MB_MOUSE_EVENT - the mouse has been clicked after pointing
outside the area defined by the function.
MB_ILLEGAL_KEY - a key that has not been defined has been
pressed.
SCL1 Version 3.1 - Reference Manual - Page 188
MouseButton - MoveFilePt
MB_MOUSE_SELECT - you have clicked your mouse after pointing
to the Mouse Button.
MB_MY_MOUSE - response to a MB_CHECK_MOUSE message if the
mouse has been clicked after pointing to the area defined.
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
int EMess;
MBData mb1;
Cls(WHITE_BLACK,CLS_ALL);
MouseButton(MB_INIT,&mb1);
mb1.LeftCol=12;
mb1.RightCol=19;
mb1.NColor=WHITE_BLACK;
mb1.RColor=BLACK_WHITE;
mb1.UpperRow=6;
mb1.Prompt="< LOAD >";;
MouseButton(MB_DRAW,&mb1);
do
{
EMess=MouseButton(MB_ACTIVE,&mb1);
}while(EMess != MB_EXIT_KEY && EMess != MB_MOUSE_SELECT);
}
-----------------------------------------------------------------
MoveFilePt
-----------------------------------------------------------------
Purpose: Moves the file pointer to the current location plus
an offset.
Prototype: int MoveFilePt(int Handle, unsigned long Bytes);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A").
Parameters:
Handle - number is given by DOS when you open a file
(integer).
Bytes - number of bytes for offset (unsigned long integer).
Example: See GetFilePt
SCL1 Version 3.1 - Reference Manual - Page 189
MoveFilePt2Offset - Num2Date
-----------------------------------------------------------------
MoveFilePt2Offset
-----------------------------------------------------------------
Purpose: Moves the file read write pointer to an offset from
the beginning of the file.
Prototype: int MoveFilePt2Offset(int Handle, unsigned long
Bytes);
Returns: The return value is 0 if no error occur or the DOS
error code if an error occur. (See Appendix "A")
Parameters:
Handle - number is given by DOS when you open a file (int).
Bytes - number of bytes for offset (unsigned long integer).
Example: See GetFilePt
-----------------------------------------------------------------
Num2Date
-----------------------------------------------------------------
Purpose: Converts an unsigned integer number representing the
number of elapsed days since January 1, 1900 to the
Day/Month/Year/WeekDay format.
Prototype: void Num2Date(unsigned int count,int *Month,int *Day,
int *Year, int *Weekday)
Returns: modifies the variables that holds the date
information.
Parameters:
count - unsigned integer number representing the number of
days that have elapsed since January 1, 1900.
Month - a valid month number (1 to 28,29, 30 or 31)(integer).
Day - a valid month number (1 to 12) (integer).
Year - a valid month year (four digits) from 1900 to 2077
(int).
WeekDay - an integer representing the day of the week
(0=Sunday, etc.)
Example: See Date2Num
SCL1 Version 3.1 - Reference Manual - Page 190
OpenFile
-----------------------------------------------------------------
OpenFile
-----------------------------------------------------------------
Purpose: Opens and existing file.
Prototype: int OpenFile(char *Filename, int *Handle,char OMode);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Filename - pointer to filename (char).
Handle - pointer to variable that will hold the DOS handle
number (int).
OMode - One of several Open modes as defined in SCL1.H:
DOS2_READ - For reading only.
DOS2_WRITE - For writing.
DOS2_RW - For reading and writing.
Any of these modes can be used with DOS 2.0 or higher.
The following can only be used with DOS 3.0 and higher. Here,
the Open Mode parameter is composed of three parts: the
Inheritance Flag, that determines if child processes will
inherit open files; the Sharing Mode, that determines if file
can be shared by several processes; and the Access Mode that
is similar to DOS 2.0 Open Mode. You must add the three flags
to get the desired open mode.
Inheritance Flag:
DOS3_INHERIT - Child process inherit open files.
DOS3_PRIVATE - No inheritance.
Sharing mode:
DOS3_COMP - Compatible with DOS 2.0
DOS3_DENY_RW - Deny read or write to other
processes.
DOS3_DENY_W - Deny write.
DOS3_DENY_R - Deny read.
DOS3_DENY_NONE - Deny none.
SCL1 Version 3.1 - Reference Manual - Page 191
OpenFile
Access mode:
DOS3_READ, DOS3_WRITE, DOS3_RW are similar to DOS
2.0.
See DOS 3.0 Technical Reference for more information.
Example:
/* This is the source code of the File2Buf function */
#include <scl1.h>
#define FILE_TOO_BIG 255
int File2Buf(char *FileName,char *Buffer,unsigned int * MaxSize)
{
int i,Handle;
unsigned int Size;
if(i=OpenFile(Filename,&Handle,DOS2_READ))
return(i);
if((Size=GetFileSize(Handle)> *MaxSize)
{
CloseFile(Handle);
return(FILE_TOO_BIG);
}
if(i=ReadFile(Handle,Buffer,Size))
{
If(i>0)
CloseFile(Handle);
return(i);
}
*MaxSize=Size;
return(CloseFile(Handle));
}
SCL1 Version 3.1 - Reference Manual - Page 192
PercentBar
-----------------------------------------------------------------
PercentBar
-----------------------------------------------------------------
Purpose: Displays a bar that graphically shows the completed
and uncompleted percentage of a given process.
Prototype: void PercentBar(int Mess,PBData *pbd,...);
Returns: This is a dialog derived function. See Appendix "E"
for a description of the general operation of these
functions.
Parameters: The percent bar information is given in a structure
type PBData as follows:
typedef struct{
int Color; Color to be used for the percent bar.
int Row; Row where to start the display of the
bar.
int Col; Column where to start the display of the
bar.
int Size; Size (number of columns) of the bar.
unsigned int Total; Total percent value to be represented.
int ForeChar; Foreground character to be used for
displaying the completed portion of the
display.
int BackChar; Background character to be used for
displaying the uncompleted portion of the
display.
}PBData;
Messages:
The following messages can be sent to PercentBar:
PB_INIT - initialize the PBData structure to NULL and set the
following default values:
Size - set to 80 column.
Total - set to 100 %.
ForeChar - set to solid block.
BackChar - set to checkered block.
SCL1 Version 3.1 - Reference Manual - Page 193
PercentBar - PushCursor - PopCursor
FB_DRAW - draw the PercentBar to the screen.
FB_UPDATE - update the PercentBar display. Each time the
function is called with this message and an additional
parameter, holding the percent value, the PercentBar display
will increment.
Example:
#include <scl1.h>
main()
{
PBData pbd;
int i;
Cls(7,CLS_ALL);
PercentBar(PB_INIT,&pbd);
pbd.Row=10;
pbd.Col=10;
pbd.Total=100;
pbd.Size=60;
PercentBar(PB_DRAW,&pbd);
for(i=1;i < 101;++i)
{
PercentBar(PB_UPDATE,&pbd,i);
WaitTime(30);
}
}
-----------------------------------------------------------------
PushCursor, PopCursor
-----------------------------------------------------------------
Purpose: Saves (PushCursor) or restores (PopCursor) the cursor
size, shape and position. The maximum number of
cursors that the function stack can hold is sixty-
four.
Prototype: int PushCursor(void);
int PopCursor(void);
Returns: Nothing.
Parameters: None.
Example:
#include <scl1.h>
#include <scl1keys.h>
SCL1 Version 3.1 - Reference Manual - Page 194
PushCursor - PopCursor
/* Shows the use of cursor related functions */
char Text[]="\n\nCursor size and position has been be saved using
PushCursor.\n\n"
"\t<*> Move the cursor around your screen using the
arrow keys\n"
"\t<*> Change cursor size using the TAB key\n"
"\t<*> Press ESC to restore original size and
position\n";
main()
{
unsigned int Key;
int CurFlag=0;
printf(Text);
PushCursor(); /* save cursor size and position */
/* let user modify size and position */
do
{
switch((Key=GetKey()))
{
case UP:
SetCurPos(GetCurLine()-1,GetCurCol());
break;
case DOWN:
SetCurPos(GetCurLine()+1,GetCurCol());
break;
case LEFT:
SetCurPos(GetCurLine(),GetCurCol()-1);
break;
case RIGHT:
SetCurPos(GetCurLine(),GetCurCol()+1);
break;
case TAB:
CurFlag ^= 1;
if(CurFlag)
BigCursor();
else
CursorOn();
break;
}
}while(Key != ESC);
/* restore original size and position */
PopCursor();
}
SCL1 Version 3.1 - Reference Manual - Page 195
PopMenu
-----------------------------------------------------------------
PopMenu
-----------------------------------------------------------------
Purpose: Similar to Mouse Menu but draws the menu box and
saves the area behind the menu box. If the left or
right arrow is pressed the routine exits and returns
a value indicating which arrow key has been pressed.
Prototype: int PopMenu(int Color,int RColor, int HColor,
struct PopMenuData *k);
Returns: Return values are "-3" if the right cursor key is
pressed, "-2" if the left cursor key is pressed,"-1"
if ESCAPE is pressed or the option number if an
option key is pressed.
Parameters: The menu information must be given as an array of
structures as follows:
struct PopMenuData{
int L1; Upper row position of the box used
for the pull-down menu.
int C1; Left column position of the box.
int L2; Lower row position of the box.
int C2; Right column position of the box.
int NumberOption; Number of options of the menu.
char *WinBuffer; Buffer to store the screen area
used when popping out the menu.
struct MenuOpt *Menust; Pointer to the MenuOption structure
corresponding to that menu.
};
The parameters passed to the function are:
NColor - color for the menu background and foreground (int).
RColor - color for the highlighted item menu bar (integer).
HColor - color for the highlighted quick selection menu item
letter (integer).
PopMenuData - pointer to the PopMenuData structure
SCL1 Version 3.1 - Reference Manual - Page 196
PopMenu - ReadFile
Example:
#include <scl1.h>
#include <scl1clor.h>
struct MenuOpt Men1[]={
2,5,"New ",'N',
3,5,"Open ",'O',
4,5,"Close ",'C',
5,5,"Save ",'S',
6,5,"Exit ",'E',
};
struct PopMenuData pmd1[]={
1,3,7,13,
5,
WinBuf1,
Men1,
};
main()
{
int Selection;
Selection=PopMenu(WHITE_BLACK,BLACK_WHITE,BLACK_WHITE+HIGHLIGHT,p
md1);
}
-----------------------------------------------------------------
ReadFile
-----------------------------------------------------------------
Purpose: Reads number of bytes from a file
Prototype: int ReadFile(int Handle,char *Buffer,
unsigned int Bytes);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Handle - handle number given by DOS when you open or create a
file (integer).
Buffer - pointer to the buffer that will hold the data.
Bytes - pointer to a variable that holds the number of bytes
to read (unsigned integer).
Example: See OpenFile
SCL1 Version 3.1 - Reference Manual - Page 197
ReadPalette - RecordFile
-----------------------------------------------------------------
ReadPalette
-----------------------------------------------------------------
Purpose: Fills an array with the active palette information.
Prototype: int ReadPalette(char *Colors);
Returns: "-1" if it cannot read the palette.
Parameter: Colors - pointer to an array that contains the
palette information. See Appendix "J".
Example:
#include <scl1.h>
main()
{
char Colors[17];
if (ReadPalette (Colors)==-1);
printf("Cannot read palette/n");
}
-----------------------------------------------------------------
RecordFile
-----------------------------------------------------------------
Purpose: Provides a method for managing record files.
Prototype: int RecordFile(int Mess,SFData *sfd);
Returns: This is a dialog derived function. See Appendix "E"
for a description of the general operation of these
functions. Returns the messages described in the
Messages section.
Parameters: The file information is given in a structure type
RFData as follows:
typedef struct{
char *FName; Pointer to a valid filename.
char *Buffer; Pointer to the buffer that holds the
record.
unsigned int DataSize; Size of data block.
long FPos; Variable (internal) that holds the
current record's file pointer (long).
SCL1 Version 3.1 - Reference Manual - Page 198
RecordFile
long FSize; Variable (internal) that holds the
file size.
long Entries; Variable (internal) that holds the
number of records.
int FHandle; Variable (internal) that holds the
file handle assigned to the file.
int Error; Variable (internal) that contain any
errors that have occurred.
}RFData;
Messages:
The following messages can be sent to RecordFile:
RF_OPEN - Open a file for record reading or writing.
RF_CREATE - Create a file for record reading or writing.
RF_FIRST - Move file pointer and read the first record.
RF_LAST - Move file pointer and read the last record.
RF_NEXT - Move file pointer and read the next record.
RF_PREVIOUS - Move file pointer and read previous record.
RF_CLOSE - Close file.
RF_ADD - Add a record to file.
RF_OPENCREATE - Opens a file for record reading or writing or
creates the file if it does not exists.
RF_WRITE - Write buffer to file.
RF_SETPOS - Set the file pointer to the desired record
number.
RF_READ - Read a record from file.
The following messages can be returned by RecordFile:
RF_OK - The requested operation was performed without errors.
RF_FILENOTFOUND - The specified file was not found.
RF_EOF - You have reached the end of the file.
SCL1 Version 3.1 - Reference Manual - Page 199
RecordFile
RF_BOF - You have reached the beginning of the file.
RF_READERR - A read error was encountered.
RF_WRITEERR - A write error was encountered.
RF_ILLEGALOP - An illegal operation has been requested.
Example:
#include <scl1.h>
/* This example shows the use of the RecordFile function to
create and use a data file organized in records */
char buffer[4]; /* data buffer */
/* this data will be stored in a RecordFile file */
char *test[]={"1","2","3","4","5","6","7"};
/* RecordFile struct */
RFData rfd={"TEST.RF",buffer,2,};
main()
{
int Mess,i;
if(Mess=RecordFile(RF_CREATE,&rfd)) /* create file */
{
printf("%i\n",Mess); /* error */
exit(-1);
}
for(i=0;i < 7;++i) /* add records */
{
rfd.Buffer=test[i];
if(Mess=RecordFile(RF_ADD,&rfd))
{
printf("%i\n",Mess); /* error */
RecordFile(RF_CLOSE,&rfd);
exit(-1);
}
/* read and print file position and size */
printf("Adding record %i, file position: %li, file size:
%li\n",i,rfd.FPos,rfd.FSize);
}
SCL1 Version 3.1 - Reference Manual - Page 200
RecordFile
printf("Press any key...\n");
GetKey();
/* make rfd.Buffer point to our buffer so that all data is
be copied to our buffer. We will read all records */
printf("Records in the order the were saved\n");
rfd.Buffer=buffer;
if(RecordFile(RF_FIRST,&rfd)==RF_OK) /* get first record*/
{
do /* print it */
{
printf("%s\n",buffer);
}while(RecordFile(RF_NEXT,&rfd) != RF_EOF);/* get next */
}
printf("Press any key...\n");
GetKey();
printf("Records in reverse order\n");
/* get last record */
if(RecordFile(RF_LAST,&rfd)==RF_OK)
{
do
{
printf("%s\n",buffer);
}while(RecordFile(RF_PREVIOUS,&rfd) != RF_BOF);
/* previous*/
}
printf("Press any key...\n");
GetKey();
printf("Record=3 modified to A\n");
/* look for record with data 3 and modify it */
if(RecordFile(RF_FIRST,&rfd)==RF_OK) /* get first */
{
do
{
if(strcmp(buffer,"3")==0) /* equal? */
{
strcpy(buffer,"A"); /* modify */
RecordFile(RF_WRITE,&rfd); /* write data */
}
}while(RecordFile(RF_NEXT,&rfd) != RF_EOF);/* get next */
}
SCL1 Version 3.1 - Reference Manual - Page 201
RecordFile - RemoveDir - RemoveExtension
/* show all records */
if(RecordFile(RF_FIRST,&rfd)==RF_OK)
{
do
{
printf("%s\n",buffer);
}while(RecordFile(RF_NEXT,&rfd) != RF_EOF);
}
RecordFile(RF_CLOSE,&rfd); /* close file */
GetKey();
}
-----------------------------------------------------------------
RemoveDir
-----------------------------------------------------------------
Purpose: Removes a directory
Prototype: int RemoveDir(char *Path);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameter: Path - char pointer to directory string.
Example: See MakeDir
-----------------------------------------------------------------
RemoveExtension
-----------------------------------------------------------------
Purpose: Removes the extension of a filename.
Prototype: char *RemoveExtension(char *Filename);
Returns: A pointer to the filename buffer.
Parameter: Filename - char pointer to filename.
Example:
#include <scl1.h>
char Filename[13]="FILE.C";
main()
{
printf("%s\n",Filename);
printf("%s\n",RemoveExtension(Filename));
}
SCL1 Version 3.1 - Reference Manual - Page 202
RenameFile
-----------------------------------------------------------------
RenameFile
-----------------------------------------------------------------
Purpose: Renames or moves a file.
Prototype: int RenameFile(char *OldName,char *NewName);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
OldName - pointer to the old filename (char).
NewName - pointer to the new filename (char).
Example:
#include <scl1.h>
main()
{
int handle;
printf("\nCreating file SCL1.TST...\n");
if(CreateFile("SCL1.TST",&handle,F_ARCHIVE))
printf("\nUnable to create file.\n");
else
CloseFile(handle);
printf("\nRenaming file SCL1.TST ==> SCL1.BAK...\n");
if(RenameFile("SCL1.TST","SCL1.BAK"))
printf("\nUnable to rename file.\n");
else
{
printf("\nDeleting SCL1.BAK...\n");
DeleteFile("SCL1.BAK");
}
}
SCL1 Version 3.1 - Reference Manual - Page 203
ResetMouse - ResetMouseCur
-----------------------------------------------------------------
ResetMouse
-----------------------------------------------------------------
Purpose: Resets mouse to default condition (cursor hidden at
the screen center and Interrupt service routine
disabled).
Prototype: void ResetMouse(void);
Returns: Nothing.
Parameters: None
Example: See CheckMouse
-----------------------------------------------------------------
ResetMouseCur
-----------------------------------------------------------------
Purpose: Resets mouse cursor to a block character.
Prototype: void ResetMouseCur(void);
Returns: Nothing
Parameters: None
Example:
include <scl1.h>
#include <scl1clor.h>
main()
{
GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0);
InitMouse(IM_SHOW);
if(MSE_MouseFl)
{
SetMouseCur('*');
WriteScreenLen(WHITE_BLACK,23,2,40,"Mouse cursor set to '*'
character");
WaitTime(300);
ResetMouseCur();
WriteScreenLen(WHITE_BLACK,23,2,40,"Mouse cursor reset to
normal");
WaitTime(300);
}
else
WriteScreenLen(WHITE_BLACK,23,2,40,"No mouse installed.");
}
SCL1 Version 3.1 - Reference Manual - Page 204
ScreenDump
-----------------------------------------------------------------
ScreenDump
-----------------------------------------------------------------
Purpose: Displays a screendump array in the screen. A
screendump array consists of characters followed by
its color attribute byte, terminated with a "0", \n
can be used to indicate end of lines.
Prototype: void ScreenDump(int Row, int Column, char *Array);
Returns: Nothing
Parameters:
Row - row position for the array display (integer).
Column - column position for array display (integer).
Array - pointer to the array buffer (char).
Example:
#include <scl1.h>
/* Each character is followed by its color attribute, a \n can
be used to indicate end of lines and a "0" must be used to
indicate the end of the array */
char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0};
main()
{
ScreenDump(10,10,Array); /* Write at line 10, column 10 */
GetKey();
ChangeDumpColor(0x70,7,Array);
ScreenDump(10,10,Array); /* Write at line 10, column 10 */
/* Change all character attributes 0x17 to 7 */
}
See also ChangeDumpColor.
SCL1 Version 3.1 - Reference Manual - Page 205
ScrollDown - ScrollUp
-----------------------------------------------------------------
ScrollDown, ScrollUp
-----------------------------------------------------------------
Purpose: Scrolls down (ScrollDown) or up (ScrollUp) a screen
area.
Prototype: void ScrollDown(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol,int Scroll);
void ScrollUp(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol,int Scroll);
Returns: Nothing
Parameters:
Color - color of the area to be scrolled (integer).
UpperRow - upper row of the area to be scrolled (int).
LeftCol - left column of the area to be scrolled (int).
LowerRow - lower row of the area to be scrolled (int).
RightCol - right column of the area to be scrolled (int).
Scroll - number of lines to scroll, if this variable is set
to "0" the whole window is cleared (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
char Mess1[]="The screen has been scrolled DOWN 1 line";
char Mess2[]="The screen has been scrolled UP 1 line";
main()
{
Box(WHITE_BLACK,0,0,0,23,79);
WaitTime(200);
ScrollDown(WHITE_BLACK,0,0,24,79,1);
WriteScreen(BLACK_WHITE,0,Center(Mess1),Mess1);
WaitTime(200);
ScrollUp(WHITE_BLACK,0,0,24,79,1);
WriteScreen(BLACK_WHITE,24,Center(Mess2),Mess2);
}
SCL1 Version 3.1 - Reference Manual - Page 206
ScrollList
-----------------------------------------------------------------
ScrollList
-----------------------------------------------------------------
Purpose: Displays a list of items enclosed in a box. The
function permits to scroll through the items using
the arrow keys or the mouse. To select an item press
the ENTER key or click the mouse on it.
Prototype: int ScrollList(int NColor,int RColor,int Row,
int Col,int Lines,char **p);
Returns: The selected item's number or "-1" if the ESC key is
pressed.
Parameters:
The scroll list information must be given in a null terminated
char pointer array.
The parameters passed to the function are:
NColor - color for the normal display of items (integer).
RColor - color for the highlighted item (integer).
Row - row position for the display of the first item of the
scroll list (integer).
Col - column position for the display of the first item of
the scroll list (integer).
Lines - number of lines to display in the box (integer).
p - pointer to a null terminated array of char pointers.
Example:
#include <scl1.h>
#include <scl1clor.h>
char *SList[]={
"Append File",
"Browse File",
"Copy file",
"Delete File",
"Merge Files",
"Move File",
"Sort File",
"Tag File",
0};
SCL1 Version 3.1 - Reference Manual - Page 207
ScrollList - ScrollWindow
main()
{
int selection;
Cls(7,CLS_ALL);
selection=ScrollList(WHITE_BLACK,BLACK_WHITE,5,40,5,SList);
SetCurPos(20,0);
if(selection > 0)
printf("\n%s was selected\n",SList[selection-1]);
else
printf("\Operation was canceled\n");
}
-----------------------------------------------------------------
ScrollWindow
-----------------------------------------------------------------
Purpose: Displays a window with a list of items. If the list
is larger than the window, or if an item's length is
larger than the display width, the display area can
scroll both horizontally and vertically. The window
can have scroll bars at the right and the bottom to
show the relative position of the text within the
window. It permits you to scroll through the items
using the cursor keys or the mouse. You can tag or
untag items by pressing the SPACEBAR or clicking the
mouse after pointing to an item. To select an item
press the ENTER key or double click the mouse after
pointing to the item.
Prototype: int ScrollWindow(int Message,SWData *p,...)
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters:
Dialog type functions receive messages and structures as
parameters. The scroll window information must be given in a
structure type SWData as follows:
typedef struct{
int NColor; Color for normal display.
int RColor; Color for reversed display.
int UpperRow; Upper row position of the window.
SCL1 Version 3.1 - Reference Manual - Page 208
ScrollWindow
int LeftCol; Left column position of the window.
int LowerRow; Lower row position of the window.
int RightCol; Right column of the window.
int FrameType; Frame type as defined in Box.
int ScrollBar; Flag to tell the function to draw
scroll bars.
int BarColor; Color for the scroll bars.
char **Array; Pointer to a null terminated array
of pointers to be displayed.
char *TagArray; Array that holds which item has
been tagged. If a null pointer is
specified the function will not
permit tagging. Array element
values of "0" and "1" indicate the
status for untagged and tagged.
int TagColor; Color to be used for displaying
tagged items.
char *Title; Char pointer to text to be
displayed as a title.
int TitleColor; Color for the title's display.
unsigned int *ExitKeys; Array of keys to exit the function.
unsigned int Lines; Variable (internal) that holds the
quantity of items in the array.
unsigned int Length; Variable (internal) that holds the
length of the longest element in
the ScrollWindow array.
unsigned int TopLine; Variable (internal) that holds the
element number that is being
displayed in the first line of the
window.
unsigned int Position; Variable (internal) that holds the
active position of the display.
Note this element should not be
modified by the calling program.
SCL1 Version 3.1 - Reference Manual - Page 209
ScrollWindow
unsigned int FirstCol; Variable (internal) that holds the
horizontal offset of the window. If
there is no horizontal scroll, its
value is "0". When there is scroll
the value will be the number of
columns to the left of the first
column displayed.
int OldVBlock; Variable (internal) that holds the
position of the vertical relative
position scroll bar block.
int OldHBlock; Variable (internal) that holds the
position of the horizontal relative
position scroll bar block.
int WindowLines; Variable (internal) that holds the
number of lines in the List Window.
int WindowCols; Variable (internal) that holds the
number of columns in the Window.
int VScroll; Variable (internal) that keeps
track if a vertical scroll is
required.
int HScroll; Variable (internal) that keeps
track if horizontal scroll is
required.
unsigned int EventInfo; Information about the keys that
have been pressed.
}SWData;
Messages:
The messages that can be sent to the ScrollWindow function are:
SW_INIT - Initialize the SWData structure to its default
values. The default values are:
NColor - set to white characters in a black background or
the normal color set by SetDialogColors.
RColor - set to black characters in a white background or
the reversed color set by SetDialogColors.
LowerRow and RightCol - one less than the screen length.
FrameType - set to frame type "1" (single line).
SCL1 Version 3.1 - Reference Manual - Page 210
ScrollWindow
ScrollBar - set to draw scroll bars.
BarColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
TagColor - set to black characters in a white background
or the reversed color set by SetDialogColors.
TitleColor - set to white characters in a black
background or the normal color set by SetDialogColors.
OldVBlock - set to "-1".
OldHBlock - set to "-1".
SW_DRAW - display the Scroll Window with the current
parameters.
SW_WRITE - write the items to the screen.
SW_ACTIVE - browse through the displayed items and permit the
selection or tagging of them using the keyboard as follows:
Key action
Up Arrow cursor one item up.
Down Arrow cursor one item down.
END cursor to end of file list.
HOME cursor to beginning of list.
Page Up cursor one screen up.
Page Down cursor one screen down.
SW_DRAW_BORDER - draw the Scroll Window's border.
SW_POSITION_BEGIN - move cursor to the first item.
SW_POSITION_END - move cursor to the last item.
SW_POSITION_UP - move cursor to the previous item.
SW_POSITION_DOWN - move cursor to the next item.
SW_SET_POSITION - move cursor to the item number passed as a
parameter.
SW_CLS - clear the list window.
SW_CHECK_MOUSE - check if the mouse has been clicked after
pointing to the area defined by the function.
SCL1 Version 3.1 - Reference Manual - Page 211
ScrollWindow
SW_UWRITE - similar to SW_WRITE but recalculates all the
internal variables and redraws the frame if needed.
SW_RESET - when this message is sent the position variables
are reset to the default value. If the exit keys have not
been defined they are set to the default exit keys.
SW_MBAR_CHARS - this message is used to change the characters
used for the scroll bars display. Default characters are
defined in header file SCL1.H as SW_MBAR_DEF (character for
the background) and SW_THUMB_DEF (character to display the
relative position). Pass the desired characters as additional
parameters (for example, ScrollWindow(SW_MBAR_CHARS, &swd,
SW_MBAR_DEF, 254);).
The messages returned by ScrollWindow are:
SW_NULL_ARRAY - no item array has been defined.
SW_OK - the requested action has been performed.
SW_EXIT_KEY - a defined exit key has been pressed.
SW_MOUSE_EVENT - the mouse has been clicked but it has not
been pointed to the area defined by the function.
SW_BUFFER_END - you have requested to move the cursor passed
the last item.
SW_BUFFER_BEGIN - you have requested to move the cursor up
and you have the first active item.
SW_ILLEGAL_KEY - an undefined key has been pressed.
SW_ILLEGAL_POSITION - you have requested to move the cursor
to an invalid position.
SW_NEW_POSITION - the cursor position has been updated.
SW_MOUSE_SELECT - one of the elements have been selected by
double clicking the mouse.
SW_MY_MOUSE - response to a SW_CHECK_MOUSE message if the
mouse has been clicked after pointing to the area defined by
the function.
SW_NEW_MOUSEPOS - you have moved the cursor by clicking the
mouse after pointing to an item.
SCL1 Version 3.1 - Reference Manual - Page 212
ScrollWindow
SW_BLOCK_MARK - this message is returned when you have marked
a series of items by dragging you mouse after clicking at an
item.
Example:
#include <scl1.h>
#include <scl1clor.h>
#include <scl1keys.h>
char *Info[]={
" BigCursor - Changes the cursor size to a block.",
" Center - Centers a string horizontally.",
" Cls - Clears a screen area.",
" CursorOff - Turns the cursor off.",
" CursorOn - Turns the cursor on (cursor visible).",
" DrawItemList - Draws an item list to the screen.",
" GetCurLine - Returns the current cursor row position.",
" GetCurSize - Returns the current cursor size.",
" ScrollUp - Scrolls up a screen area.",
" SetCurPos - Sets the cursor position.",
" SetCurSize - Sets the cursor size.",
" SetVideoMode - Sets the video mode.",
" SetVideoPage - Sets the video page.",
" SetVideo25 - Sets the display mode to 25 lines.",
" Shadow - Draws a shadow effect to a screen area.",
" Video - Detects if the video adapter in use is",
" either Monochrome, CGA or EGA.",
" WriteCharBlock - Writes a block of characters.",
0};
unsigned int ExitK[]={ESC,ENTER,0};
main()
{
int i;
SWData sw; /* Scroll Window structure */
CursorOff(); /* Turn off cursor */
InitMouse(IM_SHOW);
Cls(WHITE_BLACK,CLS_ALL);
ScrollWindow(SW_INIT,&sw); /* Initialize Scroll Window */
sw.UpperRow=2; /* Change default window size */
sw.LeftCol=4;
sw.LowerRow=15;
sw.RightCol=75;
sw.ExitKeys=ExitK;
sw.Array=Info;
sw.Title="[ Information ]";
ScrollWindow(SW_DRAW,&sw); /* Now, draw the Scroll Window */
SCL1 Version 3.1 - Reference Manual - Page 213
ScrollWindow - Select
do /* Browse window until an exit key
is pressed*/
{
i=ScrollWindow(SW_ACTIVE,&sw);
if (i==SW_ILLEGAL_KEY)
SW_MoveTo(&sw);
}while(i!=SW_EXIT_KEY && i!=SW_MOUSE_EVENT);
CursorOn();
Cls(7,CLS_ALL);
}
-----------------------------------------------------------------
Select
-----------------------------------------------------------------
Purpose: Permits the display of various options and let the
user select one of them. The active option will be
displayed with a check mark between parenthesis (√).
You can use the keyboard to move among options. A
selection can be made by clicking the left mouse
button after pointing to the desired option or by
pressing a key defined as an exit key. It can either
be used alone or as one of the field types for the
Fields2 function.
Prototype: int Select(int Message,SData1 *sd1,SData2 *sd2)
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns the messages described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The options must be passed as a null
terminated array of structures of the type SData1,
one array element for each option:
typedef struct{
int Row; Row position where the option is displayed.
int Col; Column position where the option is displayed.
char *String; Pointer to the text used to identify the
option.
}SData1;
The general information about the Select options are included in
a structure type SData2, as follows:
SCL1 Version 3.1 - Reference Manual - Page 214
Select
typedef struct{
int Color; Color for the display of the select
options.
int PRow; Row position where to display an
optional prompt.
int PCol; Column position where to display an
optional prompt.
char *Prompt; Pointer to an optional prompt or
option title.
unsigned int *ExitKeys; Array of keys defined as exit keys.
int Options; Number of options available.
int Position; Default selection.
unsigned int EventInfo; Will hold the last illegal or exit
key pressed.
}SData2;
Messages:
The messages that can be sent to the Select are:
S_INIT - initialize the SData2 structure to NULL (the SData1
structure must be initialized with the position and text
information) and set the following default values:
Color - set to black characters in a white background or
the reversed color set by SetDialogColors.
ExitKeys - ENTER, ESC, TAB and SHIFT TAB.
S_DRAW - draws the Select display.
S_ACTIVE - activates the function.
S_CHECK_MOUSE - check if the mouse has been clicked after
pointing to the area defined by the function.
S_RESET - when this message is sent the position variables
are reset to the default value. If the exit keys have not
been defined they are set to the default exit keys.
The following messages can be returned by Select:
SCL1 Version 3.1 - Reference Manual - Page 215
Select
S_NULL_ARRAY - no select item array has been defined.
S_OK - action requested was performed.
S_EXIT_KEY - a key defined as an exit key has been pressed.
S_MOUSE_EVENT - the mouse has been clicked but it has not
been pointed to the area defined by the function.
S_ILLEGAL_KEY - an illegal key has been pressed.
S_NEW_POSITION - the cursor position has been updated.
S_MY_MOUSE - response to a S_CHECK_MOUSE message if the mouse
has been clicked after pointing to the area defined by the
function.
Example:
#include <scl1.h>
#include <scl1clor.h>
#include <scl1keys.h>
unsigned int MyExitKeys[]={ENTER,ESC,0};
SData1 sd1[]={
12,35,"Male",
13,35,"Female",
0};
SData2 sd2={WHITE_BLACK,10,32,"Enter your sex:",MyExitKeys};
main()
{
int Mess;
Cls(WHITE_BLACK,0,0,24,79);
WriteScreen(WHITE_BLACK,16,22," Use ARROW KEYS to select
option,\nPress ENTER to accept, ESC to cancel");
Select(S_RESET,sd1,&sd2);
sd2.ExitKeys=MyExitKeys;
Select(S_DRAW,sd1,&sd2);
do
{
Mess=Select(S_ACTIVE,sd1,&sd2);
}while(Mess != S_EXIT_KEY);
SCL1 Version 3.1 - Reference Manual - Page 216
Select - SetBin2AsciiDel
if(sd2.EventInfo != ESC)
{
if(sd2.Position==0)
WriteScreen(WHITE_BLACK+BLINK,19,32,"You are a male.");
else
WriteScreen(WHITE_BLACK+BLINK,19,31,"You are a female");
}
else
WriteScreen(WHITE_BLACK+BLINK,19,29,"Operation was
canceled");
SetCurPos(20,0);
exit(0);
}
-----------------------------------------------------------------
SetBin2AsciiDel
-----------------------------------------------------------------
Purpose: Permits changing the comma used to in the display of
numbers when using the Bin2Ascii function to periods.
Please refer to the Bin2Ascii function.
Prototype: void SetBin2AsciiDel(int Character);
Returns: Nothing
Parameter: Character - character to be used as a separator
(integer).
Example:
#include <scl1.h>
main()
{
long l,int i;
char buffer[8];
l=999999;
Cls(7,CLS_ALL);
SetBin2AsciiDel('.');
for(i=0;i < 6;++i,l/=10)
{
WriteScreenLen(7,10,10,7,Bin2Ascii(l,buffer));
GetKey();
}
}
SCL1 Version 3.1 - Reference Manual - Page 217
SetCurPos - SetCurSize
-----------------------------------------------------------------
SetCurPos
-----------------------------------------------------------------
Purpose: Sets the cursor position.
Prototype: void SetCurPos(int Row, int Col);
Returns: Nothing
Parameters:
Row - the desired row position (integer).
Col - the desired column position (integer).
Example: See PopCursor
SetCurSize
-----------------------------------------------------------------
SetCurSize
-----------------------------------------------------------------
Purpose: Sets the cursor size.
Prototype: void SetCurSize(int CursorSize);
Returns: Nothing
Parameter: CursorSize - the desired cursor size, an unsigned
integer value that contains the scan start and end
line. To determine this value use the following
formula: Size = StartLine*256+EndLine. The start and
end lines for MONOCHROME monitors are from "0" to
"13" and for COLOR monitors from "0" to "7".
Example:
#include <scl1.h>
main()
{
int topline,bottomline;
InitVideo();
topline=0;
if(Video()==COLOR)
bottomline=7;
else
bottomline=13;
SCL1 Version 3.1 - Reference Manual - Page 218
SetCurSize - SetDialogColor - SetErrorBoxColor
printf("\nYour cursor will start growing: ");
for(topline=bottomline-1;topline > 0;--topline)
{
SetCurSize(topline * 256 + bottomline);
WaitTime(50);
}
printf("\nYour cursor will now return to normal: ");
for(;topline < bottomline;++topline)
{
SetCurSize(topline * 256 + bottomline);
WaitTime(50);
}
}
-----------------------------------------------------------------
SetDialogColor
-----------------------------------------------------------------
Purpose: Lets you define the colors that will be used when
initializing any dialog function structure.
Prototype: void SetDialogColor(int NColor,int RColor,
int HColor);
Returns: Nothing
Parameters:
NColor - normal color for the dialog functions (integer).
RColor - reversed color for the dialog functions (integer).
HColor - highlight color for the dialog functions (integer).
-----------------------------------------------------------------
SetErrorBoxColor
-----------------------------------------------------------------
Purpose: Lets you define the color for the Error Box function.
Prototype: void SetErrorBoxColor(int UColor)
Returns: Nothing
Parameter: UColor - color for Error Box messages (integer).
See also ErrorBox.
SCL1 Version 3.1 - Reference Manual - Page 219
SetFileMode
-----------------------------------------------------------------
SetFileMode
-----------------------------------------------------------------
Purpose: Sets a file's attributes (system, hidden, read only,
etc.).
Prototype: int SetFileMode(char *Filename, int NewMode);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters: A mask has been defined in SCL1.H (see GetFileMode):
They can be "ored" to "add" several attributes.
Example:
#include <scl1.h>
char Filename[]="FILE.1";
main()
{
int handle;
unsigned int FMode;
if(CreateFile(Filename,&handle,F_ARCHIVE))
exit(-1);
if(GetFileMode(Filename,&FMode))
exit(-1);
PrintFMode(FMode);
if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN))
exit(-1);
if(GetFileMode(Filename,&FMode))
exit(-1);
PrintFMode(FMode);
if(SetFileMode(Filename,F_ARCHIVE))
exit(-1);
DeleteFile(Filename);
}
PrintFMode(unsigned int FMode)
{
printf("\nFile attributes:\n\n");
if(FMode & F_READ_ONLY)
printf("\tRead Only\n");
if(FMode & F_HIDDEN)
printf("\tHidden\n");
if(FMode & F_SYSTEM)
printf("\tSystem\n");
if(FMode & F_ARCHIVE)
printf("\tArchive\n");
}
SCL1 Version 3.1 - Reference Manual - Page 220
SetHorLimit - SetVerLimit
-----------------------------------------------------------------
SetHorLimit, SetVerLimit
-----------------------------------------------------------------
Purpose: Sets the minimum and maximum mouse horizontal
position (SetHorLimit) or verical position
(SetVerLimit).
Prototype: void SetHorLimit(int Minimum,int Maximum);
void SetVerLimit(int Minimum,int Maximum);
Returns: Nothing
Parameters:
Minimum - integer value indicating the minimum position.
Maximum - integer value indicating the maximum position.
Example:
#include <scl1.h>
main()
{
InitMouse(IM_SHOW);
if(MSE_MouseFl)
{
SetHorLimit(39,39);
printf("Mouse movement has been limited to column 39");
SetVerLimit(11,11);
printf("Mouse movement has been limited to line 11");
while(!MSE_LPress);
}
else
printf("No mouse installed\n");
}
SCL1 Version 3.1 - Reference Manual - Page 221
SetInt24Colors - SetMouseCur - SetMouseIsr
-----------------------------------------------------------------
SetInt24Colors
-----------------------------------------------------------------
Purpose: Lets you define the color for the error display box
used by the TrapInt24 function.
Prototype: void SetInt24Colors(int NColor, int RColor);
Returns: Nothing
Parameters:
NColor - normal color for the TrapInt24 error display (int).
RColor - reversed color for the TrapInt24 error display
(integer).
-----------------------------------------------------------------
SetMouseCur
-----------------------------------------------------------------
Purpose: Sets mouse cursor. Any valid character can be used as
the mouse cursor.
Prototype: void SetMouseCur(int Character);
Returns: Nothing
Parameter: Character - character to be used as the mouse cursor
(int).
Example: See ResetMouseCur
-----------------------------------------------------------------
SetMouseIsr
-----------------------------------------------------------------
Purpose: Sets an interrupt service routine that is called when
the mouse moves or any of its buttons is pressed or
released.
Prototype: void SetMouseIsr(void);
Returns: Nothing
The following variables are set according to the mouse status:
MSE_LPress is set to "1" when the left button is pressed.
SCL1 Version 3.1 - Reference Manual - Page 222
SetMouseIsr
MSE_LpX is set to the mouse cursor's horizontal position when
the left mouse button is pressed.
MSE_LpY is set to the mouse cursor's vertical position when
the left mouse button is pressed.
MSE_LRel is set to "1" when the left button is released.
MSE_LrX is set to the mouse cursor's horizontal position when
the left mouse button is released.
MSE_LrY is set to the mouse cursor's vertical position when
the left mouse button is released.
MSE_RPress is set to "1" when the right button is pressed.
MSE_RpX is set to the mouse cursor's horizontal position when
the right mouse button is pressed.
MSE_RpY is set to the mouse cursor's vertical position when
the right mouse button is pressed.
MSE_RRel is set to "1" when the right button is released.
MSE_RrX is set to the mouse cursor's horizontal position when
the right mouse button is released.
MSE_RrY is set to the mouse cursor's vertical position when
the right mouse button is released.
MSE_Move is set to "1" when the mouse is moved.
MSE_MoveX holds the actual mouse cursor's horizontal
position.
MSE_MoveY holds the actual mouse cursor's vertical position.
MSE_DoubleClick is set to "1" when you double click the left
mouse button.
MSE_MouseFl is set to "1" when the mouse driver is present.
Before ending your program you must Reset the mouse using
ResetMouse or disable the interrupt service routine using
DisableMouseIsr or ResetMouse.
Example: See CheckMouse
SCL1 Version 3.1 - Reference Manual - Page 223
SetMousePos
-----------------------------------------------------------------
SetMousePos
-----------------------------------------------------------------
Purpose: Sets the mouse cursor position.
Prototype: void SetMousePos(int X, int Y);
Returns: Nothing
Parameters:
X - integer value indicating the horizontal position.
Y - integer value indicating the vertical position.
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0);
InitMouse(IM_SHOW);
if(MSE_MouseFl)
{
SetMousePos(1,1);
WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
(X,Y) = 1,1");
WaitTime(200);
SetMousePos(39,12);
WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
(X,Y) = 39,12");
WaitTime(200);
SetMousePos(78,23);
WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position
(X,Y) = 78,23");
WaitTime(200);
}
else
WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"No mouse
installed.");
}
SCL1 Version 3.1 - Reference Manual - Page 224
SetShadowColor - SetUserBox
-----------------------------------------------------------------
SetShadowColor
-----------------------------------------------------------------
Purpose: Sets the shadow color. For functions that support a
shadow effect, this function will permit you to
select the color to be XOR'ed with the background
color to produce a pleasing effect. You must specify
the color in these functions as "0". If you prefer a
solid color for the shadow effect you should specify
it as a color parameter when calling the function.
Prototype: void SetShadowColor(int Color);
Returns: Nothing
Parameter: Color - color attribute for the shadow effect (to be
XOR'ed with the background color) (integer).
Example: See Shadow
-----------------------------------------------------------------
SetUserBox
-----------------------------------------------------------------
Purpose: Lets you define a different frame type than those
available for the Box and GSSBox functions. You must
specify this frame as number 12 in these functions.
Prototype: void SetUserBox(int UpperLeft,int UpperRight,
int LowerLeft, int LowerRight,int UpperSide,
int BottomSide,int LeftSide,int RightSide);
Returns: Nothing
Parameters:
UpperLeft - character for the upper left corner of the box
frame (integer).
UpperRight - character for the upper right corner of the box
frame (integer).
LowerLeft - character for the lower left corner of the box
frame (integer).
LowerRight - character for the lower right corner of the box
frame (integer).
UpperSide - characters to be used for drawing the upper
border of the box frame (integer).
SCL1 Version 3.1 - Reference Manual - Page 225
SetUserBox - SetUserBoxLine
BottomSide - characters to be used for drawing the bottom
border of the box frame (integer).
LeftSide - characters to be used for drawing the left border
of the box frame (integer).
RightSide - characters to be used for drawing the right
border of the box frame (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
SetUserBox(21,21,21,21,21,21,21,21);
GSSBox(BLACK_WHITE,12,2,2,22,77,1,0,0);
}
-----------------------------------------------------------------
SetUserBoxLine
-----------------------------------------------------------------
Purpose: Lets you define a line type for drawing lines inside
boxes that use lines defined by using the SetUserBox
function.
Prototype: void SetUserBoxLine(int HLeft,int HRight,int VUpper,
int VLower);
Returns: Nothing
Parameters:
HLeft - horizontal left line terminating character (int).
HRight - horizontal right line terminating character (int).
VUpper - vertical upper line terminating character (integer).
VLower - vertical lower line terminating character (integer).
Example:
This example call will set a user type frame to double line, as
defined in standard frame type 0 of the Box and GSSBox functions
SetUserBoxLine(201,188,200,189,205,205,186,186);
SCL1 Version 3.1 - Reference Manual - Page 226
SetVideoMode
-----------------------------------------------------------------
SetVideoMode
-----------------------------------------------------------------
Purpose: Sets the desired video mode. See the BIOS reference
manual for the available video modes. SCL1 only
supports the 40 and 80 column text modes.
Prototype: void SetVideoMode(int NewMode);
Returns: Nothing
Parameter: NewMode - video mode as defined by the DOS (integer).
Example:
#include <scl1.h>
/* Initializes Video mode to mode 3 in case of color, EGA or VGA
or to mode 7 in case mono */
void InitVideo(void)
{
Video();
if(VC_Segment==COLOR)
SetVideoMode(3);
else
SetVideoMode(7);
}
SCL1 Version 3.1 - Reference Manual - Page 227
SetVideoPage
-----------------------------------------------------------------
SetVideoPage
-----------------------------------------------------------------
Purpose: Sets the active video page. See the BIOS reference
manual for the available video pages.
Prototype: void SetVideoPage(int NewPage);
Returns: Nothing
Parameter: NewPage - video page (supported by your display
adapter) as defined in the BIOS (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
Video();
if(VC_Monitor==VC_MDA)
{
printf("Monochrome monitors do not support video pages\n");
exit(-1);
}
Cls(WHITE_BLACK,CLS_ALL);
WriteScreen(WHITE_BLACK,10,35,"Video page 0");
WaitTime(100);
SetVideoPage(1);
Cls(BLACK_WHITE,CLS_ALL);
WriteScreen(BLACK_WHITE,10,35,"Video page 1");
WaitTime(100);
SetVideoPage(0);
WaitTime(100);
SetVideoPage(1);
WaitTime(100);
SetVideoPage(0);
}
SCL1 Version 3.1 - Reference Manual - Page 228
SetVideo25 - SetVideo28 - SetVideo4350
-----------------------------------------------------------------
SetVideo25, SetVideo28, SetVideo4350
-----------------------------------------------------------------
Purpose: SetVideo4350 sets the display mode to 43 lines (EGA
and VGA display adapters) or to 50 lines (VGA display
adapters). SetVideo28 sets the display mode to 28
lines (VGA displays). SetVideo25 resets the display
mode to 25 lines.
Prototype: void SetVideo25(void);
void SetVideo28(void);
void SetVideo4350();
Returns: Nothing
Parameters: None
Example:
#include <scl1.h>
#include <scl1clor.h>
main()
{
Video();
if(VC_Monitor != VC_VGA && VC_Monitor != VC_EGA)
{
printf("Video system does not supports 43/50 lines video
mode\n");
exit(-1);
}
SetVideo4350();
FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*');
MessageOn(BLACK_WHITE,"43/50 lines Video Mode\n
press any key...");
GetKey();
SetVideo25();
FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*');
MessageOn(BLACK_WHITE,"25 lines Video Mode\npress any key...");
GetKey();
Cls(7,CLS_ALL);
}
SCL1 Version 3.1 - Reference Manual - Page 229
Shadow
-----------------------------------------------------------------
Shadow
-----------------------------------------------------------------
Purpose: Draws a shadow to a screen area.
Prototype: void Shadow(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol);
Returns: Nothing
Parameters:
Color - color attribute of the desired shadow effect. A value
of "0" will set the shadow effect XOR'ed to the screen area.
Use SetShadowColor to specify the shadow color (integer).
UpperRow - upper row position of the area (integer).
LeftCol - left column position of the area (integer).
LowerRow - lower row position of the area (integer).
RightCol - right column position of the area (integer).
Example: See SetShadowColor
#include <scl1.h>
#include <scl1clor.h>
main()
{
FillBlock(WHITE_BLACK+HIGHLIGHT,0,0,24,79,'X');
GSSBox(WHITE_BLACK+HIGHLIGHT,0,5,20,20,60,1,0,0);
SetShadowColor(BLACK_WHITE);
Shadow(0,5,20,20,60);
GetKey();
SetShadowColor(WHITE_BLACK);
Shadow(0,5,20,20,60);
GetKey();
SetShadowColor(BLACK_BLACK+HIGHLIGHT);
Shadow(0,5,20,20,60);
}
SCL1 Version 3.1 - Reference Manual - Page 230
ShellSort
-----------------------------------------------------------------
ShellSort
-----------------------------------------------------------------
Purpose: Sort an array using a shell-sort algorithm. It
overwrites the unsorted array with the sorted
elements.
Prototype: int ShellSort(void *base,unsigned int num,
unsigned int width, int (*compare)(void
*elem1,void *elem2));
Returns: Returns "-1" if there is not enough memory or if the
array to sort has only one element. Returns "0" if
successful.
Parameters:
*compare - pointer to a user-supplied function that compares
two array elements and returns a value indicating their
relationship. ShellSort calls this compare routine and passes
pointers to two array elements. For an ascending sorting
order the compare function must return "0" if both elements
are equal, a positive value (>0) if element1 is greater than
element2 or a negative value (<0) if element1 is less than
element2. For a descending sorting order the compare function
must reverse the "greater than" and "less than" return
values.
base - pointer to the base of the array to be sorted.
SCL1 Version 3.1 - Reference Manual - Page 231
ShellSort
num - number of elements to be sorted (unsigned integer).
width - size in bytes of each array element (unsigned
integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
#include <string.h>
int compare(void *elem1,void *elem2);
typedef struct{
char line[16];
}LINE;
LINE lines[]=
{"******",
"************",
"*****",
"**************",
"*",
"*********",
"*******",
"***********",
"*************",
"********",
"****",
"***************",
"***",
"**********",
"**",};
#define LINES sizeof(lines) / sizeof(LINE)
main()
{
Cls(WHITE_BLACK,CLS_ALL);
ShellSort(lines,LINES,sizeof(LINE),compare);
DrawLines();
}
DrawLines()
{
int i;
for(i=0;i < LINES;i++)
WriteScreenLen(WHITE_BLACK,i+4,30,sizeof(LINE),
(char *)&lines[i]);
}
SCL1 Version 3.1 - Reference Manual - Page 232
ShellSort - SortPointers
int compare(void *elem1,void *elem2)
{
DrawLines();
WaitTime(10);
return(strcmp((char *)elem1,(char *)elem2));
}
-----------------------------------------------------------------
SortPointers
-----------------------------------------------------------------
Purpose: Sorts, in alphabetical order, a null terminated array
of strings.
Prototype: void SortPointers(char *p[]);
Returns: Nothing
Parameter: p - pointer to a null terminated array of char
pointers.
Example:
#include <scl1.h>
/* SortPointers demo */
char *names[]={
"Mozart",
"Villa-Lobos",
"Chopin",
"Bach",
"Schubert",
"Debussy",
"Albeniz",
"Beethoven",
"Falla",0,};
main()
{
int i;
SortPointers(names);
for(i=0;names[i];++i)
printf("%s\n",names[i]);
}
SCL1 Version 3.1 - Reference Manual - Page 233
Sound - SoundOff - SoundOn
-----------------------------------------------------------------
Sound
-----------------------------------------------------------------
Purpose: Sets a sound frequency.
Prototype: void Sound(int Freq);
Returns: Nothing
Parameter: Freq - the desired frequency in hertz (integer).
Example:
#include <scl1.h>
main()
{
SoundOn();
for(Freq=400;Freq<2000;Freq+=100)
{
Sound(Freq);
WaitTime(10);
}
SoundOff();
}
See the note definitions in header file SCL1SND.H.
-----------------------------------------------------------------
SoundOff, SoundOn
-----------------------------------------------------------------
Purpose: Turns the speaker Off or On.
Prototype: void SoundOff(void);
void SoundOn(void);
Returns: Nothing
Parameters: None
Example: See Sound
SCL1 Version 3.1 - Reference Manual - Page 234
StopWatch
-----------------------------------------------------------------
StopWatch
-----------------------------------------------------------------
Purpose: Measures elapsed time in 1/100 seconds
Prototype: long StopWatch(int Function);
Returns: Elapsed Time between calls to the function. The stop
watch is started by calling the function with the
SW_START parameter. Every time the stop watch is
stopped by calling the function with the SW_STOP
parameter it returns the elapsed time.
Parameters: See the above explanation.
Example:
#include <scl1.h>
main()
{
unsigned int i;
register unsigned int j;
long t;
StopWatch(SW_START);
for(i=0;i < 65535;++i);
t=StopWatch(SW_STOP);
printf("Your computer needs %li/100 of a second to count from
1 to 65535.\n",t);
StopWatch(SW_START);
for(j=0;j < 65535;++j);
t=StopWatch(SW_STOP);
printf("This time can be reduced to %li/100 of a second by using
a register variable.\n",t);
}
SCL1 Version 3.1 - Reference Manual - Page 235
TagItem
-----------------------------------------------------------------
TagItem
-----------------------------------------------------------------
Purpose: Displays one item and permits the user to tag or
untag it. Tag or untag an item by pressing the
SPACEBAR or by clicking the left mouse button after
pointing it. An item that has been tagged will be
displayed with a check mark (√) between parenthesis.
It can either be used alone or as one of the field
types for the Fields2 function.
Prototype: int TagItem(int Message, TIData *tg)
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. It can return a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The TagItem parameters must be passed
to a structure of the type TIData as follows.
typedef struct{
int Color; color for the display of the
TagItem.
int Row; row where the item is displayed.
int Col; column where the item is displayed.
int TagFl; flag that will have a value of "1"
if the item has been tagged and a
value of "0" if it has not been
tagged.
char *String; char pointer to the text used to
identify the TagItem.
unsigned int *ExitKeys; array of keys defined as exit keys.
unsigned int EventInfo; structure element that will hold
the last key pressed.
}TIData;
Messages:
The following messages can be sent to TagItem:
TI_INIT - initialize the TIData structure to NULL and set the
following default values:
SCL1 Version 3.1 - Reference Manual - Page 236
TagItem
Color - set to white characters in a black background or
the normal color set by SetDialogColors.
TI_DRAW - display the Tag Item with the current information.
TI_ACTIVE - take control to tag an item.
TI_CHECK_MOUSE - check if the mouse has been clicked after
pointing to the area defined by the function.
TI_RESET - when this message is sent the position variables
are reset to the default value. If the exit keys have not
been defined they are set to the default exit keys.
The following messages can be returned by TagItem:
TI_OK - the requested action has been performed.
TI_EXIT_KEY - a defined exit key has been pressed.
TI_MOUSE_EVENT - the mouse has been clicked but it has not
been pointed to the area defined by the function.
TI_ILLEGAL_KEY - an undefined key has been pressed.
TI_MY_MOUSE - the mouse has been clicked after pointing to
the area defined by the function. This message is in response
to a TI_CHECK_MOUSE message.
TI_NEW_POSITION - this message is returned when you highlight
an item either with the mouse or the keyboard.
Example:
#include <scl1.h>
#include <scl1clor.h>
#include <scl1keys.h>
unsigned int MyExitKeys[]={ENTER,ESC,0};
TIData ti={WHITE_BLACK,12,28,0,"Create Backup files"};
char Text[]="Use the SPACEBAR to toggle option ON/OFF\n"
" Press ENTER to accept, ESC to cancel";
main()
{
int Mess;
Cls(WHITE_BLACK,0,0,24,79);
SCL1 Version 3.1 - Reference Manual - Page 237
TagItem - TagList
WriteScreen(WHITE_BLACK+HIGHLIGHT,14,20,Text);
TagItem(TI_RESET,&ti);
ti.ExitKeys=MyExitKeys;
TagItem(TI_DRAW,&ti);
do
{
Mess=TagItem(TI_ACTIVE,&ti);
}while(Mess != TI_EXIT_KEY);
if(ti.EventInfo != ESC)
{
if(ti.TagFl)
WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,29,
"You have selected YES");
else
WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,30,
"You have selected NO");
}
else
WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,29,
"Operation was canceled");
SetCurPos(20,0);
exit(0);
}
-----------------------------------------------------------------
TagList
-----------------------------------------------------------------
Purpose: Displays in a ScrollBox any number of items that the
user can tag using the keyboard (spacebar) or the
mouse.
Prototype: int TagList(int NColor, int RColor,
struct TagList *tl);
Returns: Return value is a number above "0" if the user
pressed ENTER to exit, otherwise returns "-1". In
case the user has pressed ESCAPE to exit, the tagged
items are returned in the same way as they were
received.
Parameters: The taglist information is given as an array of
structures as follows:
struct TagList{
char TagFl; equals "1" if item is tagged.
SCL1 Version 3.1 - Reference Manual - Page 238
TagList
char *String; pointer to the item string.
};
Note: The TagList structure must be zero terminated.
The function is called with the following parameters:
NColor - color used for box and items (integer).
RColor - color used for selected item (integer).
tl - pointer to structure TagList. This structure is defined
in SCL1.H.
Example:
#include <scl1.h>
#include <scl1clor.h>
struct TagList tl[]={
0,"Option 1",
0,"Option 2",
0,"Option 3",
0,"Option 4",
0,"Option 5",
0,"Option 6",
0,"Option 7",
0,"Option 8",
0,"Option 9",
0};
main()
{
int i;
if(TagList(WHITE_BLACK,BLACK_WHITE,tl) != -1)
/* cancel selected? */
{
printf("\nThe following options were tagged:\n");
for(i=0;i < 9;++i)
{
if(tl[i].TagFl)
printf("%s\n",tl[i].String);
}
}
else
printf("\nOperation canceled by user\n");
}
NOTE: The new dialog type function TagList2 provides an
alternative way to accomplish this task.
SCL1 Version 3.1 - Reference Manual - Page 239
TagList2
-----------------------------------------------------------------
TagList2
-----------------------------------------------------------------
Purpose: Displays a list of items and permits tagging and
untagging of selected items. The list will scroll
vertically when the number of items is larger than
the display length using the cursor keys or the
mouse. Pressing the SPACEBAR key or clicking the
mouse in a highlighted item tags the desired item.
Prototype: int Taglist2(int Message,TLData *p,...)
Returns: This is a dialog derived function. See Appendix "E"
for a description of the general operation of these
functions. The return value is a message described in
the Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The Tag List information must be given
in a structure type TLData as follows:
typedef struct{
int NColor; Color for normal display.
int RColor; Color for reversed display).
int TColor; Color for displaying a tagged item.
int UpperRow; Upper row of the window.
int LeftCol; Left column of the window.
int LowerRow; Lower row of the window.
int RightCol; Right column of the window.
char **Array; Pointer to array of pointers to be
displayed.
char *TagArray; Char pointer to an array that hold the
tagging information about each item.
}TLData;
The messages that can be sent to the TagList2 function are:
TL_INIT - initialize the TLData structure as follows:
NColor - set to white characters in a black background or
the normal color set by SetDialogColors.
SCL1 Version 3.1 - Reference Manual - Page 240
TagList2
RColor - set to highlighted white characters in a black
background or the normal color set by SetDialogColors.
TColor - set to black characters in a white background or
the reversed color set by SetDialogColors.
UpperRow - set to row "6".
LeftCol - set to column "5" for 40 column display and
"34" for 80 column display.
LowerRow - set to row "17" for 24 row display and "29"
for 43 row display.
RightCol - set to row "34" for 40 column display and "55"
for 80 column display.
TL_DRAW - display the Tag List with the current information.
TL_ACTIVE - browse through the displayed items and permit the
selection or tagging of them using the keyboard as follows:
Key Action
Up Arrow cursor one item up.
Down Arrow cursor one item down.
END cursor to end of file list.
HOME cursor to beginning of list.
Page Up cursor one screen up.
Page Down cursor one screen down.
SpaceBar Tag or Untag an item
The messages that TagList2 can return are:
TL_OK - the requested action has been performed.
TL_CANCEL - cancel the TagList2 operation.
Example:
#include <scl1.h>
/* Shows the use of the TagList2 function */
char *options[]={
"Option 1",
"Option 2",
"Option 3",
"Option 4",
"Option 5",
SCL1 Version 3.1 - Reference Manual - Page 241
TagList2 - TagMenu
"Option 6",
"Option 7",
0};
char tarray[7];
main()
{
TLData tl;
int i,Mess;
TagList2(TL_INIT,&tl); /* initialize structure */
tl.UpperRow=6; /* modify position */
tl.LowerRow=15;
tl.LeftCol=20;
tl.RightCol=60;
tl.Array=options; /* our data*/
tl.TagArray=tarray; /* tag array */
TagList2(TL_DRAW,&tl); /* draw */
InitMouse(IM_SHOW);
Mess=TagList2(TL_ACTIVE,&tl); /* active */
if(Mess==TL_OK)
{
printf("\nThe following options were tagged:\n");
for(i=0;i < 7;++i)
{
if(tarray[i])
printf("%s\n",options[i]);
}
}
else
printf("\nOperation canceled by user\n");
}
-----------------------------------------------------------------
TagMenu
-----------------------------------------------------------------
Purpose: Displays a menu from which you can tag options. An
item is toggled on or off by moving the highlighted
bar with the arrow keys and then pressing the
SPACEBAR or by clicking the mouse. The tagged options
will be marked with a check mark. Upon exit you can
either cancel the operation or continue.
Prototype: int TagMenu(char NormalColor, char ReverseColor,
char HighlightColor, char NumOpt,struct MenuOpt*,
int XMin,int XMax,int YMin,int YMax);
SCL1 Version 3.1 - Reference Manual - Page 242
TagMenu
Returns: The returned value is "0" if the user selects the
accept option and "-1" if the operation is canceled.
The calling program must check the first character of
each selection of the structure to find out if a
selection was tagged.
Parameters: The menu information is given as an array of
structures as follows:
struct MenuOpt{
int Row; Row position for the menu item.
int Col; Column position for the menu item.
char *String; Pointer to the menu item text.
int Letter; Letter to be highlighted for fast keyboard
selection of the menu item.
};
Note: The last two options in the menu structure are the exit
control codes to the function. First the option that
cancels the operation and then the option that accepts
the operation.
The parameters passed to the function are:
NColor - color of the menu background and foreground
(integer).
RColor - color of the highlighted item menu bar (integer).
HColor - color for the highlighted quick selection menu item
letter (integer).
NumOpt - number of menu options (integer).
MenuOpt - pointer to the menu structure (char).
XMin - minimum row position of menu area (integer).
XMax - maximum row position of menu area (integer).
YMin - minimum column position of menu area (integer).
YMax - maximum column position of menu area (integer).
SCL1 Version 3.1 - Reference Manual - Page 243
TagMenu
Example:
#include <scl1.h>
#include <scl1clor.h>
struct MenuOpt mo[]={
9,35," Option 1 ",'1',
10,35," Option 2 ",'2',
11,35," Option 3 ",'3',
13,35," CANCEL ",'C',
14,35," OK ",'O',
};
main()
{
int i;
Cls(WHITE_BLACK,8,34,15,45);
Box(WHITE_BLACK,1,8,34,15,45);
if(TagMenu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,5,mo,
35,44,8,15) != -1)
{
printf("The following options were tagged:\n");
for(i=0;i < 3;++i)
{
if(mo[i].String[0] != ' ')
printf("Option %i\n",i+1);
}
}
else
printf("CANCEL was selected\n");
}
SCL1 Version 3.1 - Reference Manual - Page 244
TextWindow
-----------------------------------------------------------------
TextWindow
-----------------------------------------------------------------
Purpose: Displays text in a window.
Prototype: int TextWindow(int Message,TWData *p,...);
Returns: This is a dialog type function. See Appendix "E" for
a description of the general operation of these
functions. Returns a message described in the
Messages section.
Parameters: Dialog type functions receive messages and structures
as parameters. The text window information is given
in a structure type TWData as follows:
typedef struct{
int Color; Color for the window display.
int UpperRow; Upper row for the window display.
int LeftCol; Left column for the window display.
int LowerRow; Lower row for the window display.
int RightCol; Right column for the window display.
int FrameType; Frame type as defined in Box.
int WrapFlag; Flag to indicate if the displayed line
will be truncated or wrapped if the
line's length exceeds the window's width.
A value of "0" indicates no wrap and a
value of "1" indicates wrap.
int Position; Structure element (internal) to determine
the current position within the window.
}TWData;
The following messages can be sent to TextWindow:
SCL1 Version 3.1 - Reference Manual - Page 245
TextWindow
TW_INIT - initialize the TWData structure to null and sets
the following default values.
Color - set to white characters in a black background or
the normal color set by SetDialogColors.
LowerRow - set to maximum screen row size.
RightCol - set to maximum screen column size.
FrameType - set to single line frame.
TW_DRAW - draw the text window to the screen.
TW_WRITE - write the text information to the Text Window.
TW_CLS - clear the window.
TW_LINE_DOWN - move the cursor one line down.
TW_DRAW_BORDER - draw border around the Text Window.
TW_WAIT_ON - text will be written until the window is full
then it stops and waits for a keypress. When a key is pressed
the window is cleared.
TW_WAIT_OFF - when the window is full it returns a
TW_WINDOW_FULL message (default).
TW_RESET - when this message is sent the position variables
are reset to the default value. If the exit keys have not
been defined they are set to the default exit keys.
The following messages can be returned by TextWindow:
TW_OK - the requested action has been performed successfully.
TW_WINDOW_FULL - the Text Window is full.
Example:
#include <scl1.h>
#include <scl1clor.h>
/* TextWindow example */
char *strings[]={
"These strings will be written",
"to a Text Window, one by one.",
"Text will scroll in TTY mode",
SCL1 Version 3.1 - Reference Manual - Page 246
TextWindow
"So as to simulate a",
"DOS like screen.",
"Several control characters",
"like\t\ttab (\\t),",
"new line (\\n)\rand carriage return (\\r)",
"are supported."};
main()
{
TWData twd;
int i,Mess;
Cls(WHITE_BLACK,CLS_ALL);
TextWindow(TW_INIT,&twd); /* initialize structure */
twd.UpperRow=10; /* modify position */
twd.LowerRow=15;
twd.LeftCol=20;
twd.RightCol=60;
/* In this example we'll check for the WINDOW_FULL message
and wait for a key to be pressed before writing anything
else */
TextWindow(TW_DRAW,&twd); /* draw */
for(i=0;i < 9;++i)
{
Mess=TextWindow(TW_WRITE,&twd,strings[i]);
if(Mess==TW_WINDOW_FULL) /* window full? */
{
WriteScreen(WHITE_BLACK+HIGHLIGHT,16,21,"Press any key
for more...");
GetKey();
TextWindow(TW_CLS,&twd);
}
}
WaitTime(100);
/* Now, we'll get the same effect using the WAIT_ON message,
TextWindow will now stop and wait for a key when the
window is full */
TextWindow(TW_DRAW,&twd);
TextWindow(TW_WAIT_ON,&twd);
for(i=0;i < 9;++i)
TextWindow(TW_WRITE,&twd,strings[i]);
}
SCL1 Version 3.1 - Reference Manual - Page 247
TL_SetUserLang - TrapBIOSScreenWrite - TrapInt10 - RestoreInt10
-----------------------------------------------------------------
TL_SetUserLang
-----------------------------------------------------------------
Purpose: Lets you modify the default prompts of the TagList2
function. With this function you can customize the
default "Ok" and "Cancel" prompts. This is useful
when writing programs in languages other that
English.
Prototype: void TL_SetUserLang(char **prompt,int offset1,
int offset2);
Returns: Nothing.
Parameters:
prompt - pointer to a null terminated array of char pointers
that holds the modified prompts.
offset1 - distance from the left margin of the box where the
first mouse button ("Ok") will be displayed.
offset2 - distance from the left margin of the box where the
second mouse button ("CANCEL") will be displayed.
Example: See FB_SetUserLang
-----------------------------------------------------------------
TrapBIOSScreenWrite, TrapInt10, RestoreInt10
-----------------------------------------------------------------
Purpose: Traps BIOS interrupt 0x10 and prevents BIOS from
writing to the screen. Upon program exit the original
interrupt is restored. You can also call the
TrapInt10 and RestoreInt10 functions to get the same
results.
Prototype: int TrapBIOSScreenWrite(void);
void TrapInt10(void);
void RestoreInt10(void);
Returns: TrapBIOSScreenWrite returns "-1" if an error is
encountered.
Parameters: None
SCL1 Version 3.1 - Reference Manual - Page 248
TrapBIOSScreenWrite - TrapInt10 - RestoreInt10 - TrapInt23
Example:
one step procedure:
TrapBIOSScreenWrite(); /* BIOS and DOS screen write trapped*/
/* int 0x10 will be restored automatically on exit */
or two step procedure:
TrapInt10(); /* trap int 0x10 */
.
.
.
.
RestoreInt10(); /* restore it */
-----------------------------------------------------------------
TrapInt23
-----------------------------------------------------------------
Purpose: Traps every occurrence of the Control+Break key
combination. Global variable I23_CtrlBreakFl is
incremented every time this key combination is
pressed.
Prototype: void TrapInt23(void);
Returns: Nothing
Parameters: None
Example:
#include <scl1.h>
main()
{
TrapInt23();
printf("Press Ctrl/Break to exit\n");
do
{
}while(I23_CtrlBreakFl==0);
}
SCL1 Version 3.1 - Reference Manual - Page 249
TrapInt24
-----------------------------------------------------------------
TrapInt24
-----------------------------------------------------------------
Purpose: Critical error interrupt handler. Displays an error
box showing the critical error that has occurred.
Asks the user if he wants to retry or not the
operation.
This function is useful to avoid the familiar DOS
message "Abort, Retry, Ignore?" from appearing on
your screen. Also it gives you extra control when
you are performing a series of file operations. If a
file function returns "-1" it means that the user
does not want to retry the operation, in this case
the program can a stop the other I/O operations it
was going to perform.
This function only traps critical errors like: disk
drive door opened, printer off-line, trying to read
an unformatted disk, etc.
To initialize TrapInt24 call it at the beginning of
your program. It should be called ONLY ONCE. To alter
the error box appearance use SetInt24Colors,
Int24ShadowOff and Int24ShadowOn. The function saves
and restore the screen area where the error box is
displayed. To initialize TrapInt24 call it at the
beginning of your program.
Prototype: void TrapInt24(void);
Returns: Nothing
Parameters: None
SCL1 Version 3.1 - Reference Manual - Page 250
Tsound - Video
-----------------------------------------------------------------
TSound
-----------------------------------------------------------------
Purpose: Plays a sound of the specified frequency and for a
specified length of time (in hundredths of a second).
Prototype: void TSound(int Frequency, unsigned int Duration);
Returns: Nothing
Parameters:
Frequency - the note frequency in Hertz (integer).
Duration - length of the note in hundredths of a second
(unsigned integer).
Example:
TSound(1000,100);/*play a 1000 Hertz tone for one second.*/
See the note definitions in header file SCL1SND.H.
-----------------------------------------------------------------
Video
-----------------------------------------------------------------
Purpose: Detects if the video adapter in use is either
Monochrome or Color. Declares and defines the
variable VC_Segment (unsigned int) that holds Video
Buffer segment address. (The VideoConfig function
provides additional information)
Prototype: unsigned int Video(void);
Returns: The return value is defined in SCL1.H as MONO for
monochrome monitors, or COLOR if a color monitors.
Parameters: None
Example:
#include <scl1.h>
main()
{
if(Video()==MONO)
printf("You have a monochrome monitor\n");
else
printf("You have a color monitor\n");
}
SCL1 Version 3.1 - Reference Manual - Page 251
VideoConfig
-----------------------------------------------------------------
VideoConfig
-----------------------------------------------------------------
Purpose: Fills a structure with the current video information
for use by other functions. It will be called by the
first function that uses direct video write. Also
sets global variables VC_Monitor, VC_Mode, VC_Page,
VC_Lines, VC_Cols, VC_Retrace and VC_Segment with the
current video information.
Prototype: struct VideoData *VideoConfig(void);
Returns: a pointer to the VideoData structure.
Parameters: The video information is stored in a structure type
VideoData as follows:
struct VideoData{
int Monitor; Type of monitor detected. The
following types have been defined in
SCL1.H:
VC_MDA - Monochrome
VC_CGA - CGA monitor
VC_EGA - EGA monitor
VC_EGAM - EGA with monochrome monitor
VC_PGC - Professional graphic
VC_VGAM - VGA / monochrome
VC_VGA - VGA
VC_MCGADC - MCGA Digital
VC_MCGAAM - MCGA Analog/mono
VC_MCGAAC - MCGA Analog/color
int Mode; Active video mode.
int Page; Active video page.
int Lines; Number of rows in active video mode.
int Cols; Number of columns in active video
mode.
unsigned int Segment; Segment used by current video mode.
SCL1 Version 3.1 - Reference Manual - Page 252
VideoConfig
int Retrace; Structure element that tells the
functions to use or not to use
retrace. With a "0" value the direct
screen writes will use no retrace,
with a "1" value will use retrace. By
default this value will be set to "0"
for all video systems except VC_CGA.
};
Example:
#include <scl1.h>
char *vs[]={
"",
"Monochrome",
"CGA",
"",
"EGA",
"EGA - mono",
"PGC",
"VGA - mono",
"VGA",
"",
"MCGA - digital - color",
"MCGA - analog - mono",
"MCGA - analog - color",
};
main()
{
struct VideoData *vd;
vd=VideoConfig();
printf("\n Video system: %s\n",vs[vd->Monitor]);
printf(" Video mode: %i\n",vd->Mode);
printf(" Active page: %i\n",vd->Page);
printf(" Lines: %i\n",vd->Lines);
printf(" Columns: %i\n",vd->Cols);
printf("Buffer segment: %X\n\n",vd->Segment);
}
See also Video.
SCL1 Version 3.1 - Reference Manual - Page 253
WaitKeyMouse - WaitTime - Window
-----------------------------------------------------------------
WaitKeyMouse
-----------------------------------------------------------------
Purpose: Waits for a keystroke or pressing of the left mouse
button. The function clears the keyboard buffer on
entry.
Prototype: unsigned int WaitKeyMouse(void);
Returns: the key's Scan/Ascii code if a key is pressed.
Parameters: None
Example: See HideMouse
-----------------------------------------------------------------
WaitTime
-----------------------------------------------------------------
Purpose: Sets a delay of X hundredths of a second.
Prototype: void WaitTime(unsigned int HSec);
Returns: Nothing
Parameter: HSec - time interval in hundredths of a second.
-----------------------------------------------------------------
Window
-----------------------------------------------------------------
Purpose: Saves, clears and restores a window.
Prototype: void Window(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol,char* Flag,
char* Buffer);
Returns: Nothing
Parameters:
Color - color for the area to be cleared (integer).
UpperRow - upper left row position of the area (integer).
LeftCol - upper left column position of the area (integer).
LowerRow - lower right row position of the area (integer).
SCL1 Version 3.1 - Reference Manual - Page 254
Window
RightCol - lower right column position of the area (integer).
Flag - pointer to a variable that holds the action to be
performed:
0 -> save and clear area.
-2 -> save area only.
1 -> restore area (saved and cleared).
-1 -> restore area (saved only).
Buffer - pointer to a buffer to hold the screen information.
Notes:
1. Flag is toggled automatically every time the function is
called.
2. The buffer size is the number of characters * 2. This
size can be calculated by using the W_BUF_SIZE macro
defined in SCL1.H.
Example:
#include <scl1.h>
#include <scl1keys.h>
#include <scl1clor.h>
/* screen data is stored in these buffers, use W_BUF_SIZE macro
to calculate buffer size */
char buffer1[W_BUF_SIZE(0,0,24,79)];
char buffer2[W_BUF_SIZE(9,26,15,52)];
main()
{
char WFlag1=-2; /* save do not clear screen */
char WFlag2=0; /* save and clear screen */
Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1);
FillBlock(WHITE_BLACK,0,0,24,79,'X');
WriteScreenLen(BLACK_WHITE,24,0,70," The whole screen has
been saved, press any key...");
GetKey();
Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2);
WriteScreenLen(BLACK_WHITE,24,0,70," A second window was SAVED
AND CLEARED, press any key to restore it...");
SCL1 Version 3.1 - Reference Manual - Page 255
Window - WriteChar
GetKey();
Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2);
WriteScreenLen(BLACK_WHITE,24,0,70," Press any key to restore
the screen...");
GetKey();
Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1);
}
-----------------------------------------------------------------
WriteChar
-----------------------------------------------------------------
Purpose: Writes a character directly to the screen buffer a
specified number of times.
Prototype: void WriteChar(int Color,int Row,int Col,int Count,
int Character);
Returns: Nothing
Parameters:
Color - color for the character to be displayed (integer).
Row - row position to start display (integer).
Col - column position to start display (integer).
Count - number of times the character is written (integer).
Character - the character to be displayed (integer).
Example:
Writes 80 dashes to the screen from line 10, column 0, using
black characters in a white background.
WriteChar(0x70,10,0,80,'-');
SCL1 Version 3.1 - Reference Manual - Page 256
WriteFile - WriteOffLen
-----------------------------------------------------------------
WriteFile
-----------------------------------------------------------------
Purpose: Writes to a file. The function can also be used to
write to the standard printer, console or any other
device if the proper handle number is specified.
Prototype: int WriteFile(int Handle,char *Buffer,
unsigned int Bytes);
Returns: The DOS error code or "0" if no error occurs. (See
Appendix "A", FILE FUNCTIONS, for more information).
Parameters:
Handle - handle given by DOS when you open or create a file.
Buffer - pointer to the buffer that will hold the data.
Bytes - number of bytes to write (unsigned integer).
Example: See CloseFile
-----------------------------------------------------------------
WriteOffLen
-----------------------------------------------------------------
Purpose: Writes a string directly to the video buffer. The
display position is specified as an offset from the
home position. The length to display is specified.
If the string is shorter than the specified length,
the remaining spaces are filled with spaces.
Prototype: void WriteOffLen(int Color,int Offset,int Count,
char * String);
Returns: Nothing
Parameters:
Color - color of the desired display (integer).
Offset - offset from the home position where to display the
string. The offset is calculated as follows: number of
columns multiplied by "2" multiplied by the number of rows
plus the desired column position multiplied by "2" (integer).
Count - length to display (integer).
String - pointer to the string to be displayed.
SCL1 Version 3.1 - Reference Manual - Page 257
WriteOffLen - WriteOffset
Example:
Display a 15 character string in position offset 1500, using
white characters in a black background.
WriteOffLen(0x7,1500,15,"This is a test. ");
-----------------------------------------------------------------
WriteOffset
-----------------------------------------------------------------
Purpose: Writes a character directly to the video buffer. The
display position is specified as an offset from the
home position.
Prototype: void WriteOffset(int Color,int Offset,int Character);
Returns: Nothing
Parameters:
Color - color of the desired display (integer).
Offset - offset from the home position where to display the
string. The offset is calculated as follows: number of
columns multiplied by "2" multiplied by the number of rows
plus the desired column position multiplied by "2" (integer).
Character - character to be displayed (integer).
Example:
#include <scl1.h>
#include <scl1clor.h>
#define ROW 10
#define COL 60
char string[]="IN GIRUM IMUS NOCTE ET CONSUMIMUR IGNI";
main()
{
int offset,i;
InitVideo();
WriteScreen(BLACK_WHITE,ROW-1,23,string);
offset = ROW * VC_Cols * 2 + COL * 2;
for(i=0;i < sizeof(string)-1;++i,offset-=2)
WriteOffset(BLACK_WHITE,offset,string[i]);
}
SCL1 Version 3.1 - Reference Manual - Page 258
WriteScreen - WriteScreenC - WriteScreenR
-----------------------------------------------------------------
WriteScreen, WriteScreenC, WriteScreenR
-----------------------------------------------------------------
Purpose: Writes a string directly to the video buffer.
WriteScreen left justifies, WriteScreenC centers and
WriteScreenR right justifies the string. Supports
control character "\n".
Prototype: void WriteScreen(int Color,int Row,int Col,
char *String);
void WriteScreenC(int Color,int Row,int Col,
char *String);
void WriteScreenR(int Color,int Row,int Col,
char *String);
Returns: Nothing
Parameters:
Color - color of the desired display (integer).
Row - row position where to display the string (integer).
Col - column position where to display the string (integer).
String - pointer to the string to be displayed.
Example:
#include <scl1.h>
#include <scl1clor.h>
char Mess[]="SCL1's screen related functions will let you:\n\n"
" Θ Write directly to the screen.\n\n"
" Θ Draw boxes.\n\n"
" Θ Clear or scroll any area of your screen.\n\n"
" Θ Save and restore any screen area.\n\n"
" Θ Control cursor size and many more...";
main()
{
/* Displays the string Mess left justified in row 4, column 20 */
WriteScreen(WHITE_BLACK,4,20,Mess);
GetKey();
SCL1 Version 3.1 - Reference Manual - Page 259
WriteScreen - WriteScreenC - WriteScreenR - WriteScreenCLen
WriteScreenLen - WriteScreenRLen
/* Displays the string Mess right justified in row 4, column 20*/
WriteScreenR(WHITE_BLACK,4,20,Mess);
GetKey();
/* Displays the string Mess centered around row 10, column 40 */
WriteScreenC(WHITE_BLACK,10,40,Mess);
}
-----------------------------------------------------------------
WriteScreenCLen, WriteScreenLen, WriteScreenRLen
-----------------------------------------------------------------
Purpose: Writes a string to the video buffer. The length to
display is specified. WriteScreenCLen will center,
WriteScreenLen will left justify and WriteScreenRLen
will right justify the text. If the string is shorter
than the specified length, the remaining spaces are
filled with spaces.
Prototype: void WriteScreenCLen(int Color,int Row,int Col,
int Count,char *String);
void WriteScreenLen(int Color,int Row,int Col,
int Count,char *String);
void WriteScreenRLen(int Color,int Row,int Col,
int Count,char *String);
Returns: Nothing
Parameters:
Color - color of the desired display (integer).
Row - row position where to display the string (integer).
Col - column position where to display the string (integer).
Count - length to display (integer).
String - pointer to the string to be displayed.
SCL1 Version 3.1 - Reference Manual - Page 260
WriteScreenCLen - WriteScreenLen - WriteScreenRLen
Example:
#include <scl1.h>
#include <scl1clor.h>
char string1[]="Only the characters that fit inside the box will
written to the screen.";
char string2[]="WriteScreenLen blanks the screen if the string\n
is shorter than the length specified:";
char *strings[]={"1234567890","12345678","12345"};
main()
{
int TopRow,LeftCol,BottomRow,wide,i;
for(TopRow=LeftCol=4,BottomRow=TopRow+2,wide=72;wide > 4;
wide-=2,++LeftCol)
{
Box(BLACK_WHITE,0,TopRow,LeftCol,BottomRow,LeftCol+wide);
WriteScreenLen(BLACK_WHITE,TopRow+1,LeftCol+1,wide-1,string1);
GetKey();
}
Cls(BLACK_WHITE,10,10,14,70);
WriteScreen(BLACK_WHITE,11,17,string2);
for(i=0;i < 3;++i)
{
WriteScreenLen(BLACK_WHITE,13,35,34,strings[i]);
GetKey();
}
}
SCL1 Version 3.1 - Reference Manual - Page 261
WriteWindow
-----------------------------------------------------------------
WriteWindow
-----------------------------------------------------------------
Purpose: Writes a string to a previously created window. The
string length to display is specified. If the string
is shorter than the specified length, the remaining
spaces are filled with spaces. You can specify the
justification method. Before using this function
make sure the WData structure has been initialized
and the window created.
Prototype: void WriteWindow(WData *wd,int Row,int Col,
int Count,int Justification,char *String);
Returns: Nothing
Parameters:
WData - the address of the WData structure.
Row - row position, relative to the defined window, to start
the string display (integer). This upper left corner of the
window has 0,0 coordinates.
Col - column position, relative to the defined window, to
start the string display (integer).
Count - string length to display (integer). If the specified
screen length is larger than the string's length the rest of
the line will be cleared.
Justification - defines the way the text will be written to
the window. The following justification options have been
defined in SCL1.H:
W_LEFT - text will be left justified.
W_RIGHT - text will be right justified.
W_CENTER - text will be centered around specified
coordinates, and NOT around window. If you
want to specify the window's center you can
use the WData's HorCenter element.
String - pointer to the string to be displayed.
Example: See InitWData
SCL1 Version 3.1 - Reference Manual - Page 262
XMS_AllocExtended
-----------------------------------------------------------------
XMS_AllocExtended
-----------------------------------------------------------------
Purpose: Attempts to allocate a block of the given size out of
the pool of free extended memory. If a block is
available, it is reserved for the caller and a handle
to that block is returned to be used in all
subsequent extended memory calls.
Prototype: int XMS_AllocExtended(int *handle,
unsigned int kbytes);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block is allocated.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_ALL_EXTENDED_ALLOCATED if all extended memory is
allocated.
XMS_NO_MORE_HANDLES if all available extended memory
handles are in use.
Parameters:
handle - pointer to an unsigned integer value that will hold
a 16-bit handle to the allocated block.
kbytes - pointer to an unsigned integer value that holds the
amount of extended memory being requested in K-bytes.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 263
XMS_FreeExtended
-----------------------------------------------------------------
XMS_FreeExtended
-----------------------------------------------------------------
Purpose: Frees a block of extended memory which was previously
allocated using the XMS_AllocExtended function.
Programs which allocate extended memory should free
their memory blocks before exiting.
Prototype: int XMS_FreeExtended(int handle);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block is successfully freed.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_INVALID_HANDLE if the handle is invalid.
XMS_BLOCK_LOCKED if the handle is locked.
Parameter: handle - unsigned integer value that holds a 16-bit
handle to the allocated block.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 264
XMS_GetEMBHandleInfo
-----------------------------------------------------------------
XMS_GetEMBHandleInfo
-----------------------------------------------------------------
Purpose: Returns additional information about an extended
memory block. Use XMS_LockExtended to get the block's
base address.
Prototype: int XMS_GetEMBHandleInfo(int handle,int *LockCount,
int *FreeHandles,int *BlockSize);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block's information is found.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_INVALID_HANDLE if the handle is invalid.
Parameters:
handle - unsigned integer value that holds a handle to the
extended memory block.
LockCount - pointer to an integer value that will hold the
block's lock count.
FreeHandles - pointer to an integer value that will hold the
number of free EMB handles in the system.
BlockSize - pointer to an integer value that will hold the
block's length in K-bytes.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 265
XMS_GetVersion
-----------------------------------------------------------------
XMS_GetVersion
-----------------------------------------------------------------
Purpose: Lets you obtain the version of the Extended Memory
Manager (driver) installed in your system.
Prototype: int XMS_GetVersion(unsigned int *version);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if XMS has been initialized.
Parameter: version - pointer to an unsigned integer value that
contains the XMS driver's version number. To
determine the version number you can decode the
returned value as follows:
Two macros XMS_MAJOR_VER(i) and XMS_MINOR_VER(i) have been
defined int SCL1XMS.H. These macros extract the XMS version
number from the variable version.
To get the most significant part (MAJOR) of the version
number use the following relation:
Major=XMS_MAJOR_VER(i);
The get the least significant part (MINOR) of the version
number use the following relation:
Minor=XMS_MINOR_VER(i);
The XMS driver version number will be:
Version Number = Major.Minor
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 266
XMS_GlobalDisableA20, XMS_GlobalEnableA20
-----------------------------------------------------------------
XMS_GlobalDisableA20
-----------------------------------------------------------------
Purpose: Disable the A20 line. It should only be used by
programs which have control of the HMA.
Prototype: int XMS_GlobalDisableA20(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if HMA if the A20 is disabled.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_A20_ERROR if an A20 error occurs.
XMS_A20_ALREADY_ENABLED if the A20 line is enabled.
Parameters: None
Example: See XMS_Init
-----------------------------------------------------------------
XMS_GlobalEnableA20
-----------------------------------------------------------------
Purpose: Enable the A20 line. It should only be used by
programs which have control of the HMA. The A20 line
should be turned off before a program releases
control of the system.
Prototype: int XMS_GlobalEnableA20(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if HMA if the A20 is enabled.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_A20_ERROR if an A20 error occurs.
Parameters: None
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 267
XMS_Init
-----------------------------------------------------------------
XMS_Init
-----------------------------------------------------------------
Purpose: Initialize the Extended Memory Management functions.
Determine if a valid Extended Memory Manager (driver)
has been installed in your system.
Prototype: int XMS_Init(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if XMS has been initialized.
Parameters: None
Example:
#include <scl1xms.h>
#include <memory.h>
#include <dos.h>
/* eXtended (XMS) Memory functions */
void Pause(void);
void PrintA20Status(void);
void PrintError(unsigned int Error);
void PrintHandleInfo(int handle);
typedef struct{
unsigned int ErrorCode;
char *ErrorMess;
}XMSERRORS;
XMSERRORS xmse[]=
{
XMS_NOT_IMPLEMENTED ,"XMS function not available",
XMS_VDISK_PRESENT ,"Virtual Disk present",
XMS_A20_ERROR ,"A20 line error",
XMS_GENERAL_DRIVER_ERROR ,"General XMS driver error",
XMS_UNRECOVERABLE_ERROR ,"Unrecoverable error",
XMS_HMA_NOT_EXIST ,"HMA does not exist",
XMS_HMA_IN_USE ,"HMA already in use",
XMS_HMA_NOT_ALLOCATED ,"HMA is not allocated",
XMS_A20_ALREADY_ENABLED ,"A20 is already enabled",
XMS_ALL_EXTENDED_ALLOCATED,"All XMS memory allocated",
XMS_NO_MORE_HANDLES ,"No more handles available",
XMS_INVALID_HANDLE ,"Invalid handle number",
XMS_INVALID_SOURCE_HANDLE ,"Invalid source handle",
XMS_INVALID_SOURCE_OFFSET ,"Invalid source offset",
SCL1 Version 3.1 - Reference Manual - Page 268
XMS_Init
XMS_INVALID_DEST_HANDLE ,"Invalid destination handle",
XMS_INVALID_DEST_OFFSET ,"Invalid destination offset",
XMS_INVALID_LENGTH ,"Invalid length",
XMS_INVALID_OVERLAP ,"Invalid overlap",
XMS_PARITY_ERROR ,"Parity error",
XMS_BLOCK_NOT_LOCKED ,"Block not locked",
XMS_BLOCK_LOCKED ,"Block locked",
XMS_LOCK_COUNT_OVERFLOW ,"Lock count overflow",
XMS_LOCK_FAIL ,"Lock fail",
XMS_UMB_SMALL_AVAILABLE ,"Smaller UMB available",
XMS_UMB_NOT_AVAILABLE ,"UMB not available",
XMS_UMB_INVALID_SEGMENT ,"Invalid segment",
};
char CompOkStr[]="\tCompare OK\n";
char CompErrStr[]="\tCompare ERROR\n";
/* struct used to move or copy data from extended memory */
XMSMove xmove;
char TestData[80]="This string will be used to test XMS
functions";
main()
{
unsigned int available,total,i,handle;
char buffer[sizeof(TestData)];
void far *p;
/* initialize, check if XMS driver is present */
if(XMS_Init() != XMS_OK)
{
printf("No XMS available\n");
exit(-1);
}
else
printf("\n\nSCL1 Version 3.1 eXtended (XMS) Memory Test\n");
XMS_GetVersion(&i); /* get version number */
/* add 0x30 to returned value to get ASCII code */
memset(buffer,0,sizeof(buffer));
buffer[0]=XMS_MAJOR_VER(i) + 0x30;
buffer[1]='.';
buffer[2]=XMS_MINOR_VER(i) + 0x30;
printf("XMS Version %s\n\n",buffer);
SCL1 Version 3.1 - Reference Manual - Page 269
XMS_Init
/* High Memory Area Test */
printf("High Memory Area (HMA) Test\n");
if((i=XMS_RequestHMA())==XMS_OK)
{
/* allocated OK */
printf("\tHMA allocated...\n");
/* enable the A20 line so that we can access HMA */
if((i=XMS_GlobalEnableA20())==XMS_OK)
{
_fmemcpy(XMS_HMA,(void far *)TestData,sizeof(TestData));
printf("\tData copied to HMA...\n");
/* copy HMA to local buffer */
memset(buffer,0,sizeof(buffer));
_fmemcpy((void far *)buffer,XMS_HMA,sizeof(buffer));
if(memcmp(buffer,TestData,sizeof(TestData))==0)
printf(CompOkStr);
else
printf(CompErrStr);
}
else
printf("\tError enabling A20 line, cannot access HMA\n");
/* free HMA */
XMS_ReleaseHMA();
printf("\tReleasing HMA...\n");
}
else
PrintError(i);
Pause();
/* Extended Memory Test */
printf("Extended Memory Test\n");
SCL1 Version 3.1 - Reference Manual - Page 270
XMS_Init
if((i=XMS_QueryFreeExtended(&available,&total))==XMS_OK &&
available > 0)
{
printf("\tLargest available block: %u KB\n",available);
printf("\tTotal available memory: %u KB\n",total);
/* allocate all memory */
if((i=XMS_AllocExtended(&handle,available))==XMS_OK)
{
printf("\tSuccesful allocation of %u KB...\n",available);
printf("\tCopying data to allocated memory...\n");
/* copy TestData buffer to extended memory */
xmove.bytes=(unsigned long)sizeof(TestData);
xmove.shandle=0;
xmove.source=(void far *)TestData;
xmove.dhandle=handle;
xmove.destination=0;
if((i=XMS_MoveExtended(&xmove))==XMS_OK)
{
/* copy extended memory to local buffer */
memset(buffer,0,sizeof(buffer));
xmove.bytes=sizeof(TestData);
xmove.shandle=handle;
xmove.source=0;
xmove.dhandle=0;
xmove.destination=(void far *)buffer;
if((i=XMS_MoveExtended(&xmove))==XMS_OK)
{
if(memcmp(TestData,buffer,sizeof(TestData))==0)
printf(CompOkStr);
else
printf(CompErrStr);
}
else
PrintError(i);
}
else
PrintError(i);
/* get handle information */
PrintHandleInfo(handle);
Pause();
SCL1 Version 3.1 - Reference Manual - Page 271
XMS_Init
/* Lock/Unlock Test */
printf("Lock/Unlock Test\n\tLocking allocated
memory...\n");
if((i=XMS_LockExtended(handle,&p))==XMS_OK)
{
printf("\tLocked block 32-bit linear address:
%lX\n",p);
PrintHandleInfo(handle);
printf("\tUnlocking allocated memory...\n");
XMS_UnlockExtended(handle);
PrintHandleInfo(handle);
}
else
PrintError(i);
/* Reallocating Test */
Pause();
printf("Reallocating Test\n");
/* reallocate buffer to 1kb */
if((i=XMS_ReallocExtended(handle,1))==XMS_OK)
{
printf("\tBlock reallocated to 1 KB\n");
/* get handle info */
PrintHandleInfo(handle);
}
else
printf("\tError reallocating\n");
/* free memory */
XMS_FreeExtended(handle);
printf("\tReleasing Extended memory...\n");
}
else
printf("\tError Allocating\n");
}
Pause();
/* A20 Line Test */
printf("A20 Line Test\n");
PrintA20Status();
SCL1 Version 3.1 - Reference Manual - Page 272
XMS_Init
if((i=XMS_LocalEnableA20())==XMS_OK)
{
printf("\tLocally enabling A20 line...\n");
XMS_LocalEnableA20();
PrintA20Status();
printf("\tLocally disabling A20 line...\n");
XMS_LocalDisableA20();
PrintA20Status();
}
else
PrintError(i);
Pause();
/* Upper Memory Blocks Test */
printf("Upper Memory Block (UMB) Test\n");
/* By requesting 0xffff paragraphs, the largest available
block size will be reported if UMB blocks are available*/
if((i=XMS_RequestUMB(0xffff,&p,&available))==XMS_OK ||
i==XMS_UMB_SMALL_AVAILABLE)
{
printf("\tUMB available, allocating largest block
available...\n");
if(i==XMS_UMB_SMALL_AVAILABLE)
{
if((i=XMS_RequestUMB(available,&p,&available))!=XMS_OK)
PrintError(i);
else
{
printf("\tUMB Size: %li bytes\n\tUMB Address: %X\n",
(long) available * 16L,FP_SEG(p));
printf("\tCopying data to allocated memory...\n");
_fmemcpy(p,(void far *)TestData,sizeof(TestData));
memset(buffer,0,sizeof(buffer));
_fmemcpy((void far *)buffer,p,sizeof(TestData));
if(memcmp(buffer,TestData,sizeof(TestData))==0)
printf(CompOkStr);
else
printf(CompErrStr);
printf("\tReleasing UMB...\n");
XMS_ReleaseUMB(p);
}
}
}
else
PrintError(i);
}
SCL1 Version 3.1 - Reference Manual - Page 273
XMS_Init
void PrintError(unsigned int Error)
{
int i;
for(i=0;i < sizeof(xmse) /sizeof(XMSERRORS);++i)
{
if(xmse[i].ErrorCode==Error)
{
printf("\t%s\n",xmse[i].ErrorMess);
return;
}
}
printf("\tUnknown error #%X\n",Error);
}
void Pause(void)
{
printf("-- more --");
GetKey();
printf("\r \n");
}
void PrintHandleInfo(int handle)
{
int lcount,fhandle,bsize;
XMS_GetEMBHandleInfo(handle,&lcount,&fhandle,&bsize);
printf("\tHandle Report:\n");
printf("\t\tFree Handles: %i\n",fhandle);
printf("\t\tAllocated Block Lock Count: %i\n",lcount);
printf("\t\tAllocated Block Size: %i KB\n",bsize);
}
void PrintA20Status(void)
{
unsigned int i;
int j;
if((j=XMS_QueryA20(&i))==XMS_OK)
{
if(i==XMS_A20_ENABLED)
printf("\tA20 enabled\n");
else
printf("\tA20 NOT enabled\n");
}
else
PrintError(j);
}
SCL1 Version 3.1 - Reference Manual - Page 274
XMS_LocalDisableA20, XMS_LocalEnableA20
-----------------------------------------------------------------
XMS_LocalDisableA20
-----------------------------------------------------------------
Purpose: Cancels a previous call to the XMS_LocalEnableA20
function. It should only be used by programs which
need direct access to extended memory.
Prototype: int XMS_LocalDisableA20(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if HMA if the A20 is disabled.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_A20_ERROR if an A20 error occurs.
XMS_A20_ALREADY_ENABLED if the A20 line is enabled.
Parameters: None
-----------------------------------------------------------------
XMS_LocalEnableA20
-----------------------------------------------------------------
Purpose: Enables the A20 line. It should only be used by
programs which need direct access to extended memory.
Programs which use this function should disable the
A20 line before releasing control of the system.
Prototype: int XMS_LocalEnableA20(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if HMA if the A20 is enabled.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_A20_ERROR if an A20 error occurs.
Parameters: None
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 275
XMS_LockExtended
-----------------------------------------------------------------
XMS_LockExtended
-----------------------------------------------------------------
Purpose: Locks an extended memory block and returns its base
address. Locked memory blocks are guaranteed not to
move. The 32-bit pointer is only valid while the
block is locked. Locked blocks should be unlocked as
soon as possible. A block does not have to be locked
before using XMS_MoveExtended function.
Prototype: int XMS_LockExtended(int handle,void far **bpt);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block is locked.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_INVALID_HANDLE if the handle is invalid.
XMS_LOCK_COUNT_OVERFLOW if the block's lock count
overflows.
XMS_LOCK_FAIL if the lock fails.
Parameters:
handle - an unsigned integer value that holds a 16-bit handle
to the allocated block.
bpt - pointer to a far pointer that will hold the 32 bit
address of the memory block.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 276
XMS_MoveExtended
-----------------------------------------------------------------
XMS_MoveExtended
-----------------------------------------------------------------
Purpose: Transfers a block of data from one location to
another. It is primarily used for moving blocks of
data between conventional memory and extended memory,
however it can be used for moving blocks within
conventional memory and within extended memory.
Prototype: int XMS_MoveExtended(XMSMove *);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the move is successful.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_INVALID_SOURCE_HANDLE if shandle is invalid.
XMS_INVALID_SOURCE_OFFSET if the Source Offset
(*source)is invalid.
XMS_INVALID_DEST_HANDLE if dhandle is invalid.
XMS_INVALID_DEST_OFFSET if the Destination Offset
(*destination) is invalid.
XMS_INVALID_LENGTH if the length (bytes) is invalid,
must me a pair number.
XMS_INVALID_OVERLAP if the move has an invalid
overlap.
XMS_PARITY_ERROR if a parity error occurs.
XMS_A20_ERROR if an A20 error occurs.
Parameters: The function receives a pointer to a XMSMove type
structure as follows:
typedef struct{
unsigned long bytes; Number of bytes to transfer.
unsigned int shandle; Handle of source block. This value
will be "0" if the source block
belongs to conventional memory.
SCL1 Version 3.1 - Reference Manual - Page 277
XMS_MoveExtended, XMS_QueryA20
void far *source; If shandle is set to "0", this pointer
is a standard segment:offset pair to
memory that is directly accessible by
the processor. If shandle is not "0"
this variable is a 32 bit offset to
extended memory block.
unsigned int dhandle; Handle of destination block. This
value will be "0" if the source block
belongs to conventional memory.
void far *destination; If dhandle is set to "0", this pointer
is a standard segment:offset pair to
memory that is directly accessible by
the processor. If dhandle is not "0"
this variable is a 32 bit offset to
extended memory block.
}XMSMove;
Example: See XMS_Init
-----------------------------------------------------------------
XMS_QueryA20
-----------------------------------------------------------------
Purpose: This function checks to see if the A20 line is
physically enabled. It does this in a hardware
independent manner by seeing if "memory wrap" occurs.
Prototype: int XMS_QueryA20(int *A20status);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_A20_NOT_ENABLED message if the A20 line is not
physically enabled.
XMS_A20_ENABLED message if the A20 line is enabled.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
Parameter: A20status - pointer to an integer value that will
hold the A20 line status. It is used to return this
status to the calling program.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 278
XMS_QueryFreeExtended, XMS_ReallocExtended
-----------------------------------------------------------------
XMS_QueryFreeExtended
-----------------------------------------------------------------
Purpose: Returns the size of the largest available extended
memory block in the system. The HMA is not included
in the returned value even if it is not in use.
Prototype: int XMS_QueryFreeExtended (unsigned int *FreeKB,
unsigned int *TotalKB);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_ALL_EXTENDED_ALLOCATED if all extended memory is
allocated.
Parameters:
FreeKB - pointer to an unsigned integer that will hold the
size of the largest free extended memory block in K-bytes.
TotalKB - pointer to an unsigned integer value that will hold
total amount of free extended memory in K-bytes.
Example: See XMS_Init
-----------------------------------------------------------------
XMS_ReallocExtended
-----------------------------------------------------------------
Purpose: Attempts to reallocate an unlocked extended memory
block so that it becomes the newly specified size.
Prototype: int XMS_ReallocExtended(int handle,
unsigned int newsize);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block is reallocated.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_INVALID_HANDLE if the handle is invalid.
SCL1 Version 3.1 - Reference Manual - Page 279
XMS_ReallocExtended - XMS_ReleaseHMA - XMS_RequestHMA
XMS_BLOCK_LOCKED if the block is not locked
XMS_ALL_EXTENDED_ALLOCATED if all available extended
memory is allocated.
XMS_NO_MORE_HANDLES if all available extended memory
handles are in use.
Parameters:
handle - unsigned integer value that holds a handle to the
unlocked extended memory block to reallocate.
newsize - pointer to an unsigned integer value that holds the
new size for the extended memory block in K-bytes.
Example: See XMS_Init
-----------------------------------------------------------------
XMS_ReleaseHMA, XMS_RequestHMA
-----------------------------------------------------------------
Purpose: These functions attempt to reserve and release the
64K-16 byte high memory area (HMA) to allow other
programs to use it. Programs which allocate the HMA
must release it before exiting.
Prototype: int XMS_ReleaseHMA(void);
int XMS_RequestHMA(void);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if HMA if the HMA is successfully assigned
(XMS_RequestHMA) or released (XMS_ReleaseHMA).
XMS_NOT_IMPLEMENTED if function is not implemented.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_HMA_NOT_EXIST if the HMA does not exist.
XMS_HMA_NOT_ALLOCATED if the HMA was not allocated.
XMS_HMA_IN_USE is already in use.
Parameters: None
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 280
XMS_ReleaseUMB - XMS_RequestUMB
-----------------------------------------------------------------
XMS_ReleaseUMB
-----------------------------------------------------------------
Purpose: Frees a previously allocated Upper Memory Block
(UMB). When an UMB has been released, any code or
data stored in it becomes invalid and should not be
accessed.
Prototype: int XMS_ReleaseUMB(void far *UMBpt);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block was released.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_UMB_INVALID_SEGMENT if the UMB segment number is
invalid.
Parameter: UMBpt - far pointer to the segment number of the
upper memory block.
Example: See XMS_Init
-----------------------------------------------------------------
XMS_RequestUMB
-----------------------------------------------------------------
Purpose: Attempts to allocate an Upper Memory Block (UMB). If
the function fails, the size of the largest free UMB
is returned. UMBs are located below the 1MB address
boundary. The A20 Line does not need to be enabled
before accessing an allocated UMB. UMBs are paragraph
aligned. To determine the size of the largest
available UMB, attempt to allocate one with a size of
FFFFh.
Prototype: int XMS_RequestUMB(unsigned int para,
void far **UMBpt,unsigned int *ActualSize);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the request is granted.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
SCL1 Version 3.1 - Reference Manual - Page 281
XMS_RequestUMB - XMS_UnlockExtended
XMS_UMB_NOT_AVAILABLE if no UMBs are available.
Parameters:
para - size of requested memory block in paragraphs. One
paragraph is 16 Bytes of memory (unsigned int.)
UMBpt - pointer to a far pointer to the segment number of the
upper memory block if the request is granted.
ActualSize - pointer to an unsigned integer value that will
hold the actual size of the allocated block in paragraphs or
the size of the largest available UMB in paragraphs (unsigned
integer).
Example: See XMS_Init
-----------------------------------------------------------------
XMS_UnlockExtended
-----------------------------------------------------------------
Purpose: Unlocks a locked extended memory block. Pointers into
the block become invalid and should no longer be
used.
Prototype: int XMS_UnlockExtended(int handle);
Returns: Returns one of the following messages defined in
header file SCL1XMS.H:
XMS_OK if the block is unlocked.
XMS_VDISK_PRESENT if a VDISK device is detected.
XMS_NOT_IMPLEMENTED if the function is not
implemented.
XMS_INVALID_HANDLE if the handle is invalid.
XMS_BLOCK_NOT_LOCKED if the block is not locked
Parameter: handle - unsigned integer value that holds a handle
to the allocated block.
Example: See XMS_Init
SCL1 Version 3.1 - Reference Manual - Page 282
YesNo
-----------------------------------------------------------------
YesNo
-----------------------------------------------------------------
Purpose: Displays a YES/NO query box with mouse control
buttons. The original screen is restored on exit.
Prototype: int YesNo(int NColor,int RColor,int Selection,
char *p);
Returns: A value of "1" is returned if YES is selected. A
value of "2" if NO is selected. You can use the
YN_YES and YN_NO constants defined in SCL1.H.
Parameters:
NColor - color for the YES/NO box (integer).
RColor - color of the selected option (integer).
Selection - default selection (integer).
p - pointer to the question whose answer is seeked.
Example:
#include <scl1.h>
#include <scl1clor.h>
int Color1=WHITE_BLACK;
int Color2=BLACK_WHITE;
#define OK 1
#define CANCEL 2
main()
{
YN_SetPosition(4,10); /* Set position of the YesNo box to the
upper left corner of the screen */
/* use YN_SetUserLang to modify prompts to OK and CANCEL */
YN_SetUserLang("< OK >",2,0x1800,"< CANCEL >",11,0x2e00);
do
{
if(YesNo(Color1,Color2,OK,"Turn YesNo Box\nShadow On?")==OK)
YesNoShadowOn();
if(YesNo(Color1,Color2,OK,"Turn YesNo Box\nShadow Off?")==OK)
YesNoShadowOff();
}while(YesNo(Color1,Color2,CANCEL,"Exit to DOS?")!= OK);
}
SCL1 Version 3.1 - Reference Manual - Page 283
YesNoShadowOff - YesNoShadowOn - YNSetPosition
-----------------------------------------------------------------
YesNoShadowOff, YesNoShadowOn
-----------------------------------------------------------------
Purpose: Displays or disable a shadow effect when using the
YesNo function. After any of these functions is
called all subsequent calls to the YesNo function
will be displayed with (or without) a shadow effect.
Prototype: void YesNoShadowOff(void);
void YesNoShadowOn(void);
Returns: Nothing.
Parameters: None.
Example: See YesNo
See YNSetPosition and YN_SetUserLang.
-----------------------------------------------------------------
YNSetPosition
-----------------------------------------------------------------
Purpose: Permits changing the position of a YesNo display to
any place in the screen.
Prototype: void YN_SetPosition(int UpperRow,int LeftCol);
Returns: Nothing
Parameters:
UpperRow - upper row position of the YesNo box (integer).
LeftCol - left column position of the YesNo box (integer).
Example: See YesNo
See YesNoShadowOff, YesNoShadowOn and YN_SetUserLang.
SCL1 Version 3.1 - Reference Manual - Page 284
YN_SetUserLang
-----------------------------------------------------------------
YN_SetUserLang
-----------------------------------------------------------------
Purpose: Modify the default YesNo prompts with your own
prompts.
Prototype: void YN_SetUserLang(char *prompt1,int offset1,
unsigned int key1,char *prompt2,int offset2,
unsigned int key2);
Returns: Nothing
Parameters:
prompt1 - char pointer to the first prompt, the "Yes" option.
offset1 - position from the border of the box where to
display the first prompt (integer).
key1 - scan code of the key to be used for selecting prompt1
(unsigned int).
prompt2 - char pointer to the second prompt, the "No" option.
offset2 - position from the border of the box where to
display the second prompt (integer).
key2 - scan code of the key to be used for selecting prompt2
(unsigned int).
Example: See YesNo
See YesNoShadowOff, YesNoShadowOn and YNSetPosition.
SCL1 Version 3.1 - Reference Manual - Page 285
YN_SetFrame
-----------------------------------------------------------------
YN_SetFrame
-----------------------------------------------------------------
Purpose: Modify the default YesNo frame type.
Prototype: void YN_SetFrame(int FrameType);
Returns: Nothing
Parameters:
FrameType - any of the frame types defined in Box or GSSBox
(integer).
See YesNo, YesNoShadowOff, YesNoShadowOn and YNSetPosition.
SCL1 Version 3.1 - Reference Manual - Page 286
ZWindow
-----------------------------------------------------------------
ZWindow
-----------------------------------------------------------------
Purpose: Restores a screen area with a zooming effect.
Prototype: void ZWindow(int Color,int UpperRow,int LeftCol,
int LowerRow,int RightCol,int Frame,char* Buffer);
Returns: Nothing
Parameters:
Color - color for the area to be restored (integer).
UpperRow - upper left row position of the area (integer).
LeftCol - upper left column position of the area (integer).
LowerRow - lower right row position of the area (integer).
RightCol - lower right column position of the area (integer).
Frame - frame type to be used (integer).
Buffer - pointer to a buffer that holds the screen
information. The buffer size is the number of characters * 2.
This size can be calculated by using the W_BUF_SIZE macro
defined in SCL1.H.
Example: See Window
SCL1 Version 3.1 - Reference Manual - Page 287
Appendix "A" - File Related Functions
SCL1's file related functions rely on DOS services to work with files.
They provide an alternative to the standard library functions with an
easier way to trap and display error related information.
You can classify errors in two groups; critical and non-critical.
Critical errors are those that generate an interrupt 0x24 (a disk
drive door left opened, for example). This type of error generates the
DOS message "Retry, Abort, Ignore?". Non-critical errors (file not
found, for example) are reported by the system but do not generate an
interrupt 0x24.
SCL1 functions handles non-critical errors in a simple way. Most file
functions return zero if the operation was successful, otherwise they
return the DOS error code. Your program can then process the error
code or you can call the ErrorBox function that will display it. You
can change the ErrorBox default error messages (see ErrorBox).
SCL1 has the TratInt24 function to deal with DOS critical errors. Call
this function at the beginning of your program (it must be done only
once) and any subsequent critical errors will be handled by SCL1. If
DOS generates an interrupt 0x24, instead of its standard message, a
window will be opened in the screen and a message indicating the type
of error, asking the user if he wants or not to retry operation, will
be displayed. On exit the original screen will be restored.
Once you have initialized TrapInt24, SCL1's file related functions
will return -1 to indicate a DOS critical error if the user decided
NOT TO retry the operation. If the user decides to retry the operation
and it is completed successfully, no error code is reported.
As you see, trapping critical errors and non-critical errors can be
easily integrated to your program by using TrapInt24 and ErrorBox.
SCL1's way of displaying error message is specially appropriate for
programs that are not command-line oriented. Also notice that you
don't have to use ErrorBox when a critical error is reported since
TrapInt24 has its own way of displaying error messages.
Refer to the DOS Technical Reference for more information about error
code numbers.
The following pseudo-code shows how to deal with errors:
Returned error code > than 0 ?
Call ErrorBox with error number.
Error code = -1 ?
DOS Critical error, the user choose not to retry
operation. No need to call ErrorBox since the error
message has already been displayed by TrapInt24.
else
Operation was successful.
SCL1 Version 3.1 - Reference Manual - Page 288
Appendix "A" - File Related Functions
The following list show the most common DOS error codes:
2 File not found
3 Path not found
4 No handles left
5 Access denied
6 Invalid handle
15 Invalid drive
16 Attempt to remove current directory
29 Write Fault
30 Read Fault
SCL1's Error codes:
255 File too big (used by File2Buf)
-1 Dos Critical error
-2 Drive not valid (used by GetDiskFreeSpace)
SCL1 gives you direct access to DOS file related functions. You need
to understand DOS's way of working with files for using them. There
are many books that could help you. The general procedure is:
You must first open or create a file. Use OpenFile to open an
existing file (error is reported if the file is not found) or
CreateFile to create a file, if the file is not found or truncates
an existing file to 0. When you open or create a file DOS gives
you a "Handle". A handle is a number that you will use to refer to
this file when performing any other operations like reading,
writing, etc.
Once you have a handle to a file you can write or read data. To do
it use ReadFile or WriteFile. These functions will read or write
any number of bytes to or from a buffer you specify. Files
functions under DOS have a read/write pointer. When you read 200
bytes the file pointer will point to byte 201. This means that
next time you read, you will read byte 201. This pointer is
automatically moved by ReadFile and WriteFile. You can move this
pointer using MoveFilePt and MoveFilePt2Offset.
Once you have finished working with your file, you must close the
file using CloseFile.
As you see working with files under DOS is a three step process:
1) Open/Create File, 2) Read/Write, 3) Close File.
SCL1 offers another way to work with files. You can read a file to
a buffer or write a buffer to a file in just one step using
File2Buf and Buf2Disk. You don't have to care about opening or
closing files with this functions. But you will have to read or
write the whole file/buffer when you use them.
SCL1 Version 3.1 - Reference Manual - Page 289
Appendix "B" - Mouse Related Functions
SCL1 mouse related functions are based on an interrupt service routine
(ISR) that updates a series of variables according to the mouse
current state. If you do not initialize this ISR you would not be able
to use the mouse routines. They can be initialized in several ways.
The CheckMouse function can be used to check if the mouse hardware/
software is installed:
if(CheckMouse())
we have a mouse !
Once you have verified that the mouse is installed you should reset
the mouse software to its defaults using ResetMouse and then proceed
to install the ISR using SetMouseIsr:
if(CheckMouse())
{
ResetMouse();
SetMouseIsr();
Now you can call any mouse related functions. Before returning to DOS
the program must un-install the ISR using ResetMouse(). Failure to do
so might cause unpredictable problems.
These steps can be simplified by using the InitMouse function that
performs all the above operations including resetting the ISR:
If you want a visible mouse cursor use:
InitMouse(IM_SHOW);
If you want an invisible mouse cursor use:
InitMouse(IM_NO_SHOW);
Once the mouse is initialized a series of variables are updated
according to mouse events (see SetMouseIsr). Your program can check
these variables to read the mouse position and the mouse buttons
state. If you change video modes you should reset the mouse and re-
initialize it. The re-initialization MUST NOT be done using InitMouse:
InitMouse(IM_SHOW);
ResetMouse();
SetVideoMode(1);
if(CheckMouse())
{
ResetMouse();
SetMouseIsr();
ShowMouse();
}
SCL1 Version 3.1 - Reference Manual - Page 290
Appendix "C" - Screen Related Functions
SCL1's screen related functions write directly to the video buffer.
Configuration according to monitor type is done automatically when the
first screen related function is called. During this process, SCL1's
Video function will determine the type of monitor, the video buffer
address and if it is necessary to wait for retrace to reduce snow.
To find about the video configuration your program will be using you
should call VideoConfig. This function returns a pointer to a
structure that holds the information about the current video adapter.
The structure format is as follows:
struct VideoData{
int Monitor; /* Monitor type */
int Mode; /* Active video mode */
int Page; /* Active video page */
int Lines; /* Number of lines in video mode */
int Cols; /* Number of columns in video mode */
unsigned int Segment; /* video buffer segment address */
int Retrace; /* =1 if retrace is to be done */
};
Monitor types are define in SCL1.H :
VC_MDA = Monochrome
VC_CGA = CGA monitor
VC_EGA = EGA monitor
VC_EGAM = EGA with monochrome monitor
VC_PGC = Professional graphic
VC_VGAM = VGA / monochrome
VC_VGA = VGA
VC_MCGADC = MCGA Digital
VC_MCGAAM = MCGA Analog/mono
VC_MCGAAC = MCGA Analog/color
If you do not need all the video information you can call Video. This
functions returns whether the monitor is color or mono:
if(Video()==COLOR)
color monitor
else
mono monitor
NOTE: COLOR & MONO are defined in SCL1.H as the segment address of the
Video Buffer (0xb800 for color 0xb000 for mono).
SCL1 Version 3.1 - Reference Manual - Page 291
Appendix "C" - Screen Related Functions
SCL1 video functions work only in alphanumeric video modes. You can
initialize your system to one of these modes (3 in case of color, 7 in
case of mono) by calling InitVideo at the beginning of your program.
Most of the times this won't be necessary since they are the default
modes, but is not a bad idea to use InitVideo just to make sure. Be
aware that when you call InitVideo the screen will be cleared and the
cursor moved to the screen's home position. Remember that version 2.0
of SCL1 supports only video modes 0 - 3 and 7.
SCL1's screen related functions always write to the active video page.
You can change the video page using SetVideoPage. Be sure to specify a
valid page for your system. You can force a function to write to a
non-active video page by modifying the VC_Page variable before calling
the desired video function, be sure to restore the correct value of
VC_Page.
Retrace will be done only if a CGA type adapter is found. SCL1
functions will not wait for the video retrace if an EGA adapter is
found. Yet you can force them to do the retrace by changing the
variable VC_Retrace to 1. For example:
if(Video()==COLOR)
VC_Retrace=1;
You must set this variable to 1 AFTER having called Video or any other
screen related function.
EGA 43 lines and VGA 50 lines are now supported by SCL1. SetVideo4350
sets the mode to 43 or 50 lines depending on the monitor you have.
SetVideo25 restores video mode to the default 25 lines.
SCL1 Version 3.1 - Reference Manual - Page 292
Appendix "D" - SCL1 Header Files
SCL1.H - SCL1 structures, functions prototypes and constant
definitions.
SCL1KEYS.H - SCAN-ASCII code of most used keys. F1 - F10 (with shift,
alt and control), numeric key-pad keys and A-Z (with alt and control),
and the extra keys that enhanced keyboards have (F11 - F12, etc) are
defined.
SCL1CLOR.H - Color definitions.
Example: WHITE_BLUE stands for white characters on blue
background.
Colors can be highlighted and the blink attribute is also defined.
Example:
WHITE_RED | HIGHLIGHT
WHITE_RED | BLINK
SCL1HUGE.H - Definition of huge functions.
SCL1SND.H - Definition of musical notes frequency in hertz to be used
with sound related functions.
Syntax TS_X[y]?, were:
TS = TSound id
X = musical note (C,D,E,F,G,A,B)
y = s means sharp, f means flat (optional)
? = octave (1 - 7)
Examples: TS_Df4 = D flat, fourth octave
TS_C4 = C, fourth octave (middle C)
SCL1EMS - This header file includes the function prototypes for the
Expanded Memory Functions.
SCL1XMS - This header file includes the function prototypes for the
Extended Memory Functions.
SCL1 Version 3.1 - Reference Manual - Page 293
Appendix "E" - Dialog Type Functions
SCL1 includes several functions that utilize a dialog scheme. The idea
behind these functions is to make them as flexible as possible,
permitting the programmer to set or specify any available parameter.
This flexibility adds complexity and, in order to make them as
friendly as possible, a dialog scheme has been used.
During program development a need arises to perform a complex task.
For example; let's say you need to get user input, but you want to add
the flexibility of being able to check for a help key or for a
keystroke combination that will insert a block at the current cursor
position. You might need a window were the user can browse through a
list of items, and you want to know exactly at any moment what item is
being highlighted by the user so that you can display help information
or show the selected item in another window. These types of
requirements usually require you to write a custom procedure. Most
library functions are not designed to handle these special
requirements. The dialog type functions have been designed to permit
you to handle these types of problems.
To permit this type of flexibility, the dialog type functions make use
of message interchanges. You can call the function as many times as
required, each time requesting an action. The function will return a
message that gives you the results or status of the requested action.
The general way to use this functions is as follows. You can call the
function with an initialization message. This will take care of
initializing the structure elements to some predetermined values and
setting the function's initial conditions. Then you can call the
function with a message requesting a display. This will instruct the
function to draw or display to the screen the desired object (like a
scroll window display). Now that there is a display you will like to
make the function active so that it can perform the desired task.
While the function is active it will keep sending back messages
informing you of what is happening, for example, that an illegal key
has been pressed (so display an error or help message, or beep the
console to warn the user, etc.) or that the cursor has changed
position, etc. You can then analyze these returned messages and
respond with a given action or you can ignore them. In fact, you can
request the function to do anything it is capable of doing, for
example, in the case of data entry field (like LineEditor), to move
the cursor to any position, reformat or even change the data, insert a
new character, etc. The messages have been defined in the header file
as english-like messages to permit a friendly interface.
Most of the parameters needed to configure the functions are included
as elements of one or several structures. These structure(s) need to
be initialized before the function is called. They contain many
parameters and it might look as if they involve much effort to define.
With the aid of SSG (SCL1 Screen Generator) you can define them very
easily. Refer to the included SSG reference manual.
SCL1 Version 3.1 - Reference Manual - Page 294
Appendix "E" - Dialog Type Functions
SENDING MESSAGES TO DIALOG TYPE FUNCTIONS
Every effort has been made to make the dialog functions as uniform as
possible. Most functions use the same messages to perform similar
tasks.
INITIALIZING THE PARAMETER STRUCTURES:
You can define the parameter structures in two different ways. One
way is to indicate a value for each parameter. The other way is to
call the functions with a "INIT" message, this will assign default
values to most parameters, that you can later modify. Which method
to use depends on how many of the parameters you will like to have
control of.
For example, let us initialize a ScrollWindow structure using the
two methods:
1) Using SW_INIT message:
#include <scl1.h>
/* This is the data you want to display in your scroll window */
char *swdbuf[]={
"First Item",
"Second Item",
0};
main()
{
SWData swd;
/* This initializes the structures to the default values (see
each function description for details). Once it has been
initialized you need to modify only the desired parameters */
ScrollWindow(SW_INIT,&swd);
/* Modify the size of our scroll window */
swd.UpperRow=6;
swd.LeftCol=26;
swd.LowerRow=17;
swd.RightCol=52;
/* And specify our data address */
swd.Buffer=swdbuf;
SCL1 Version 3.1 - Reference Manual - Page 295
Appendix "E" - Dialog Type Functions
2) Defining the structure as static data:
#include <scl1.h>
/* This is the data you want to display in your scroll window */
char *swdbuf[]={
"First Item",
"Second Item",
0};
/* All the parameters required to define the Scroll Window go into
this structure (size, color, position, etc.). */
SWData swd={7,15,6,26,17,52,0,1,15,swdbuf,0,0," Scroll
Window",7,0,0,0,0,0,0,0,0,0,0,0,0,0};
/* Since all the parameters have been defined there is no need to
change any of them */
THE "RESET" MESSAGE:
Dialog function structures have several position related
variables. When you declare your structure as static data you do
not need to call the function with an "INIT" message. You should
call the function with a "RESET" message to make sure that all
these variables are reset. This message also checks for undefined
ExitKeys an sets this element to default values if the have not
been defined.
Let us continue with the previous example of an application of the
ScrollWindow function. Let us assume that the structure has been
defined as static data. Our program should look like this:
main()
{
/* The RESET message resets the internal position related
variables (in this case, it makes sure that we start at the
first item. It also checks for any parameter that may have not
been specified in the structure (in this example the ExitKeys
have not been specified). You should always call a dialog
function using the "RESET" message when you are not using the
"INIT" message unless you desire the cursor to appear over an
specific item */
ScrollWindow(SW_RESET,&swd);
}
SCL1 Version 3.1 - Reference Manual - Page 296
Appendix "E" - Dialog Type Functions
THE "DRAW" MESSAGE:
Once your structure is defined and initialized you can send
messages to it. The first message usually is "DRAW", this message
instructs the function to display the information to the screen.
In our example using the ScrollWindow function the "DRAW" message
should be sent like this:
ScrollWindow(SW_DRAW,&swd);
After sending this message you should see a the Scroll Window
displayed in the screen.
THE "ACTIVE" MESSAGE:
The "ACTIVE" message permits you to have the function perform the
specific task it has been designed to do. Messages are constantly
returned by the dialog type function. If you are using the
LineEditor function, the "ACTIVE" message permits you to edit the
entry field, for the ScrollWindow function, this message lets you
browse through the window, etc.
When you send this message the function will retain the program
control until some event occurs. For example, in the case of
ScrollWindow, if the user presses the DOWN or UP arrow keys to
change a highlighted item, ScrollWindow will return a NEW_POSITION
message. If the user presses an undefined key (it could be F1 to
request Help) an ILLEGAL_KEY message is returned. You can ignore
the returned message or respond to it. In our previous example of
a the ScrollWindow function the code should look like this:
do
{
Mess=ScrollWindow(SW_BROWSE,&swd);
}while(Mess != SW_EXIT_KEY);
Since when an "ACTIVE" message is sent the function retains the
program control until an event occurs, we should place this
function call within in a loop. In this case any returned message
is ignored except "EXIT_KEY" which means that a key defined as an
exit key has been pressed. The user will be able to browse until
one of these keys is pressed. Exit Keys can individually be
defined for each function. You can add any desired Exit Keys by
defining a null-terminated array were all the ExitKeys' SCAN/ASCII
codes values are specified, for example:
unsigned int MyExitKeys[]={ESC,ENTER,0};
NOTE: This example needs header file SCL1KEYS.H.
SCL1 Version 3.1 - Reference Manual - Page 297
Appendix "E" - Dialog Type Functions
Once you have defined your Exits Keys you initialize the structure
ExitKeys element:
swd.ExitKeys=MyExitKeys;
You can also call the function with the "INIT" and "RESET"
messages to set the ExitKeys to default values (see each function
description)
THE "POSITION_BEGIN" MESSAGE
When you call the function with this message the cursor moves to
the start of the data buffer.
The "POSITION_END" MESSAGE
When you call the function with this message the cursor moves to
the end of the data buffer.
The "POSITION_UP" MESSAGE
When you call the function with this message the cursor moves one
position towards the end of the data buffer in the LineEditor
function, to the next field for the Fields2 function and to the
next item in all other functions.
The "POSITION_DOWN" MESSAGE
When you call the function with this message the cursor moves one
position towards the start of the data buffer in the LineEditor
function, to the next field for the Fields2 function and to the
next item in all other functions.
The "SET_POSITION" MESSAGE
When you call the function with this message the cursor moves to
the specified position. This function call requires you to send an
additional parameter (see explanation below).
The "CHECK_MOUSE" MESSAGE
Normally Dialog type functions handle the mouse input by
themselves but when you have several Dialog type functions at the
same time on the screen and your program detects that the mouse
has been clicked you can send this message to any dialog function.
If the mouse was clicked inside a function screen area it will
return a MY_MOUSE message, in any other case it returns a
MOUSE_EVENT message. This call is useful for determining under
what conditions the mouse has been clicked.
SCL1 Version 3.1 - Reference Manual - Page 298
Appendix "E" - Dialog Type Functions
MESSAGES THAT DIALOG TYPE FUNCTIONS CAN RETURN
THE "OK" MESSAGE.
This message is returned when you have called a Dialog type
function with the "DRAW", "INIT" or "RESET" messages, and the
action was performed as requested.
THE "EXIT_KEY" MESSAGE.
This message is returned when one of the keys, defined as an Exit
Key, has been pressed. It's SCAN/ASCII code is stored in the
structure element "EventInfo".
THE "ILLEGAL_KEY" MESSAGE:
Each function uses several keys (like PgUp, PgDn etc.) to perform
common operations and checks for the use of the defined ExitKeys.
If any other key is pressed, it returns an ILLEGAL_KEY message and
stores the key's SCAN/ASCII code in the structure's EventInfo
element.
You can respond to this message for performing a given action.
Let us see an example in which we use the ILLEGAL_KEY message to
display a help screen and at the same time display the highlighted
item in a secondary window:
do
{
Mess=ScrollWindow(SW_ACTIVE,&swd);
if(Mess==SW_ILLEGAL_KEY) /* Illegal key pressed? */
{
/* The structure's EventInfo element is common to all
Dialog function. It holds the value of the key that was
pressed when you receive and EXIT_KEY or ILLEGAL KEY
message. */
if(swd.EventInfo == F1) /* Help Key? */
... Display help code would go here ....
else /* Unknown key */
... Display error message, beep etc.
}
SCL1 Version 3.1 - Reference Manual - Page 299
Appendix "E" - Dialog Type Functions
/* Let's now display the highlighted item in a secondary
window, the structure Position element can be used as an
index to our data array */
WriteScreen(7,24,30,swdbuf[swd.Position]);
}while(Mess != SW_EXIT_KEY);
You can send other messages while you're inside this loop. For
example, in this loop the item at the cursor position is deleted
from the list when the DELETE key is pressed:
do
{
Mess=ScrollWindow(SW_BROWSE,&swd);
if(Mess == SW_ILLEGAL_KEY && swd.EventInfo == DEL)
{
/* DeleteItem would be an user defined function that
deletes an item from your list */
DeleteItem(swd.Position);
/* Now redraw your data */
Mess=ScrollWindow(SW_DRAW,&swd);
}while(Mess != SW_EXIT_KEY);
THE "MOUSE EVENT" MESSAGE
This message is returned when the mouse has been clicked outside
the function screen area. You can check mouse variables MSE_LpX
and MSE_LpY to get the actual position were the mouse was clicked.
THE "MY_MOUSE" MESSAGE
When you send a "CHECK_MOUSE" message to a dialog function it
checks if the mouse was clicked inside it's screen area. In this
case it will return a "MY_MOUSE" message. You can then send an
"ACTIVE" messages so that the function gets control and services
the mouse event. In the case the mouse was clicked outside it's
screen area a "MOUSE_EVENT" message is returned.
THE "BUFFER_END" MESSAGE
This message is returned when the user has tried to move the
cursor passed the last element (or end) of the buffer. This
message can be safely ignored unless you want to display an error
or warning. (This message is not supported by all Dialog
functions).
SCL1 Version 3.1 - Reference Manual - Page 300
Appendix "E" - Dialog Type Functions
THE "BUFFER_BEGIN" MESSAGE
This message is returned when the user has tried to move the
cursor passed the first element (or beginning) of buffer. This
message can be safely ignored unless you want to display an error
or warning. (This message is not supported by all Dialog
functions).
THE "ILLEGAL_POSITION" MESSAGE
This message is returned when you send a "SET_POSITION" message
but the position parameter is not valid.
THE "NEW_POSITION" MESSAGE
This message is returned when the user has moved the cursor to a
new position. You can get the current position from the "Position"
structure element.
Every effort has been made to make these functions to be called very
similarly.
STRUCTURE ELEMENTS COMMON TO ALL DIALOG FUNCTIONS:
The following structure elements are common to all Dialog type
functions:
Colors - Colors are defined using one or more of the following
structure elements:
Color - For functions that use only one color.
Functions that use more than one color:
NColor - Normal Color
RColor - Reversed Color
HColor - Highlight Color
TColor - Color used to tag items.
Screen Position - Screen coordinates are specified using one or more
of the following structure elements:
Row,Col - Row & column position.
UpperRow,LowerRow,LeftCol,RightCol - Used in functions that
must define a screen area. UpperRow/LeftCol indicate the
window's top left coordinate and LowerRow/RightCol the lower
right corner.
SCL1 Version 3.1 - Reference Manual - Page 301
Appendix "E" - Dialog Type Functions
EventInfo - When the user press an undefined key or an exit key it's
SCAN/ASCII code value is stored in this element.
ExitKeys - Pointer to a null-terminated array of unsigned integers. It
must be initialized to the SCAN/ASCII code values of the keys that are
to be defined as ExitKeys. (see the examples above).
NOTE: ExitKeys are checked by Dialog Functions before the default
editing keys. This means you can override a defined editing key or
invalidate its use by defining it as an ExitKey.
Position - This element holds the current cursor position. Some
functions may have more than one variable.
ADDITIONAL PARAMETERS
Some messages (for example SET_POSITION) require that you send an
additional parameter. This parameter is always the last parameter:
NewPosition=123;
ScrollWindow(SW_SET_POSITION,&swd,NewPosition);
In this example, the new position is specified by the NewPosition
variable.
FUNCTIONS DERIVED FROM DIALOG FUNCTIONS
Dialog functions offer a lot of power and flexibility. Several of the
new functions included in this version of SCL1 utilize them. These new
functions follow the general working procedure of the "INIT", "RESET",
"DRAW" and "ACTIVE" messages previously described, but they retain the
program control until on of the ExitKeys is pressed. In future
versions of SCL1 a monitoring facility will be added to this functions
to improve their flexibility. The FileBox2 and WFileBox are examples
of these dialog derived functions. The next example shows how to use
these functions:
#include <scl1.h>
main()
{
FBData fbd;
char buffer[80];
memset(buffer,0,sizeof(buffer));
FileBox2(FB_INIT,&fbd); /* Initialize */
fbd.UpperRow=10; /* Modify size & position */
fbd.LeftCol=20;
fbd.LowerRow=20;
SCL1 Version 3.1 - Reference Manual - Page 302
Appendix "E" - Dialog Type Functions
fbd.RightCol=60;
fbd.Buffer=buffer; /* Use our buffer */
FileBox2(FB_DRAW,&fbd);
FileBox2(FB_ACTIVE,&fbd);
}
Its important to know if a function is a true DIALOG function or a
DIALOG-DERIVED function.
SCL1 Version 3.1 - Reference Manual - Page 303
Appendix "F" - Extended Memory Functions
SCL1's extended memory handling functions adhere to the Extended
Memory Specifications (XMS), version 2.0, jointly developed by
Microsoft Corporation, Lotus Development Corporation, Intel
Corporation, and AST Research, Inc. These specifications are the
copyright and property of Microsoft Corporation, Lotus Development
Corporation, Intel Corporation, and AST Research, Inc. In this
Appendix, some information has been literally copied or adapted from
these specifications.
It is beyond the scope of this appendix to explain in detail the
Extended Memory Specifications or how to use them in your programs. It
is recommended that you obtain the XMS specification document from any
of its developers in order to take full advantage of these functions.
Extended Memory allows programs to utilize additional memory found in
Intel's 80286 and 80386 based machines. The XMS specifications allow a
consistent and machine independent manner to handle this memory. With
some restrictions, XMS adds almost 64K to the 640K which programs can
access directly. Depending on available hardware, XMS may provide even
more memory to DOS programs. XMS also provides programs with a
standard method of storing data in extended memory.
In order to use the Extended Memory function and XMS driver must be
installed in your system by including a DEVICE= statement in the
machine's CONFIG.SYS file. It must be installed prior to any other
devices or TSRs which use it.
DEFINITIONS:
Extended Memory - Memory in 80286 and 80386 based machines which
is located above the 1MB address boundary.
High Memory Area (HMA) - The first 64K of extended memory. The
High Memory Area is unique because code can be executed in it
while in real mode. The HMA officially starts at FFFF:10h and ends
at FFFF:FFFFh making it 64K-16 bytes in length.
Upper Memory Blocks (UMBs) - Blocks of memory available on some
80x86 based machines which are located between DOS's 640K limit
and the 1MB address boundary. The number, size, and location of
these blocks vary widely depending upon the types of hardware
adapter cards installed in the machine.
Extended Memory Blocks (EMBs) - Blocks of extended memory located
above the HMA which can only be used for data storage.
A20 Line - The 21st address line of 80x86 CPUs. Enabling the A20
line allows access to the HMA.
SCL1 Version 3.1 - Reference Manual - Page 304
Appendix "F" - Extended Memory Functions
XMM - Extended Memory Manager. A DOS device driver which
implements XMS. XMMs are machine specific but allow programs to
use extended memory in a machine-independent manner. For example;
HIMEM.SYS, currently distributed by Microsoft.
USING XMS FUNCTIONS:
To use SCL1's XMS functions first, the program should determine if an
XMS driver is installed. It can then use any of the available XMS
functions. The following list show the correspondence of SCL1's XMS
functions to the function numbers in the XMS specifications.
SCL1 Function XMS Function Number
----------------------- -------------------
XMS_Init
XMS_GetVersion 0
XMS_RequestHMA 1
XMS_ReleaseHMA 2
XMS_GlobalEnableA20 3
XMS_GlobalDisableA20 4
XMS_LocalEnableA20 5
XMS_LocalDisableA20 6
XMS_QueryA20 7
XMS_QueryFreeExtended 8
XMS_AllocExtended 9
XMS_FreeExtended 10
XMS_MoveExtended 11
XMS_LockExtended 12
XMS_UnlockExtended 13
XMS_GetEMBHandleInfo 14
XMS_ReallocExtended 15
XMS_RequestUMB 16
XMS_ReleaseUMB 17
SCL1 Version 3.1 - Reference Manual - Page 305
Appendix "G" - Expanded Memory Functions
SCL1's Expanded Memory Functions adhere to the LIM version 4.0
specifications. Because they are standardized, you avoid potential
compatibility problems with other expanded memory programs that also
adhere to the memory manager specification. Most standard functions
are included, although not all advanced LIM functions have been
implemented. In order to use the EMM functions your system must have
expanded memory capabilities and a suitable Expanded Memory Manager
should have been installed. In this Appendix, some information has
been literally copied or adapted from these specifications.
It is beyond the scope of this appendix to explain in detail the
Expanded Memory Specifications or how to use them in your programs. It
is recommended that you obtain the LIM specification document from any
of its developers in order to take full advantage of these functions.
USING EXPANDED MEMORY FUNCTIONS
The general procedure to use the EMS functions is: Determine if EMM is
installed by calling the EMS_Init function. Determine if enough
expanded memory pages exist for your application. Allocate expanded
memory pages. Get the page frame base address. Map in expanded memory
pages. Read/write/execute data in expanded memory, just as if it were
conventional memory. Return expanded memory pages to expand memory
pool before exiting.
The following list show the correspondence of SCL1's EMS functions to
the function numbers in the EMS specifications.
SCL1 Function EMM Function Number
----------------------- -------------------
EMS_Status 1
EMS_PageAdress 2
EMS_AvailableLogPages 3
EMS_Alloc 4
EMS_Map 5
EMS_Free 6
EMS_Version 7
EMS_SavePageMap 8
EMS_RestorePageMap 9
EMS_GetHandleCount 12
EMS_GetHandlePages 13
EMS_GetAllHandlePages 14
EMS_MapMultipleEMS 17
EMS_Realloc 18
EMS_GetHandleName 20
EMS_SetHandleName 20
EMS_Move 24
EMS_Exchange 24
SCL1 Version 3.1 - Reference Manual - Page 306
Appendix "H" - Keyboard Macros
A macro is series of keystrokes stored in memory or in a disk file
that, when recalled, will perform as if they were keyed in into the
keyboard. The number of macros that can be defined at once is limited
only by the available memory. Macros can be of up to 32,000 keystrokes
in size. The macro capability is available on any function that uses
SCL1's keyboard handling functions, they will not be available if you
call any of the standard library keyboard functions.
If you do not use these macro capabilities, the keyboard related
functions will work exactly as in previous versions of SCL1. When you
invoke any of the macro related function, the keyboard functions will
check to see if any defined macro or trap keyboard combination has
been entered and when detected act on them.
Macros are stored in a structure type MACROData defined in SCL1.H as
follows:
typedef struct{
unsigned int key;
unsigned int size;
unsigned int *buffer;
}MACROData;
where,
key is the key to trigger or invoke the macro.
size is the maximum number of keys to accept for the macro.
buffer is a pointer to the buffer that will hold the macro.
Every macro defined will occupy one array member of this type. All
macro related functions will read and/or write to this structure.
The simplest way to use the macros is by using the MCR_Init function.
This function will do almost everything for you. Every time the key
defined for starting and stopping the macro recording process is
pressed this function will send messages to your own user defined
macro handling function. With these messages you can control the flow
of the macro recording and storing. Once a macro is recorded it will
immediately become available. You can save to disk the recorded macros
using MCR_SaveMacro and you can retrieve macros using MCR_ReadFile,
see MCR_Init for an example.Other functions permit more control of the
macro creation and use process.
SCL1 Version 3.1 - Reference Manual - Page 307
Appendix "I" - Common Compiler Errors
When compiling programs you may encounter several Compiler or Linker
errors. In this appendix the most common errors and some possible
solutions are listed.
Unresolved externals - You can get this message from the linker if
one or more variables or functions specified in your source code
is not found. If it refers to an SCL1 function it means that you
have not specified the SCL1 library module needed to properly link
your program. See USING SCL1 for more information.
Fix-up overflow - You can get this message if you compile your
program using a memory model and then thy to link it with an SCL1
library module of a different memory model. Memory models of must
be the same.
Code exceeds 64K - If you get this message while using the small
or compact memory model it means that you must switch to the
medium or large memory model.
Stack & Data exceeds 64K - If you get this message while using the
small or medium memory model it means you that you must switch to
the compact or large memory model. You can also get this message
while using the compact or large memory model if your initialized
static data cannot fit into the default data segment. Try removing
some of this data by allocating and initializing buffers using
malloc. If this is not possible you have several options depending
on your compiler. With Borland compilers switch to the huge
memory model. With the Microsoft compilers you can try declaring
some of this data (big items) with the far keyword, this will
force the compiler to move the data to a far data segment. You can
also compile your source with the Gt switch. This switch tells the
compiler to put large data items into far memory.
Too many segments - The Microsoft linker has a default limit in
the number of segments. You can increase this limit by adding the
switch SE followed by the number of desired segments (for example,
SE:256).
undefined struct or constant - If it is an SCL1 related identifier
you have to add the include directive with the proper SCL1's
header file. See Appendix "D"
SCL1 Version 3.1 - Reference Manual - Page 308
Appendix "J" - Character Definition Tables
In text modes, characters are defined in character definition tables.
The following is a VGA character matrix defining character ASCII 1:
matrix byte representation
0 0 0 0 0 0 0 0 0x00
0 0 0 0 0 0 0 0 0x00
0 1 1 1 1 1 1 0 0x7e
1 0 0 0 0 0 0 1 0x81
1 0 1 0 0 1 0 1 0xa5
1 0 0 0 0 0 0 1 0x81
1 0 0 0 0 0 0 1 0x81
1 0 1 1 1 1 0 1 0xbd
1 0 0 1 1 0 0 1 0x99
1 0 0 0 0 0 0 1 0x81
1 0 0 0 0 0 0 1 0x81
0 1 1 1 1 1 1 0 0x7e
0 0 0 0 0 0 0 0 0x00
0 0 0 0 0 0 0 0 0x00
0 0 0 0 0 0 0 0 0x00
0 0 0 0 0 0 0 0 0x00
Each number represents one bit. Since each line has 8 bits it can be
represented by one byte. A character definition matrix like this is
normally represented by an array of 16 bytes starting with the top
line (as seen at the right column). When displayed in the screen, bits
set to "1" are displayed in the foreground color and bits set to "0"
in the background color.
EGA and VGA displays have several character tables used for several
text modes:
Video Mode 25x40 25x80 28x80 43x80 50x80
VGA 8x16 8x16 8x14 N/A 8x8
EGA 8x14 8x14 N/A 8x8 N/A
In EGA and VGA monitors we can modify these tables to create new fonts
and even display a graphic in a text screen mode (see BMPCNV.C
included in the sample files). SCL1's ModifyCharSet function can be
used to modify the character table that the BIOS is currently using.
You have to be careful to pass the correct character matrix, so you
need to check the type of monitor and the active video mode in order
to know which character matrix to use. The easiest way to work with
character definitions is to use SSG. Start SSG and modify any
character using the SSG character editor (Video Menu, Modify Character
Set) and then generate the source (Character Set object). When you
save the file SSG will create a function that checks the monitor type
and video mode to select the correct character matrix.
SCL1 Version 3.1 - Reference Manual - Page 309
Appendix "J" - Character Definition Tables
Once a character has been modified it will be active until you change
the video mode. SCL1's InitVideo function can be used to reset all
characters to their default. You can also restore character
definitions from a previously copied table in one of two ways.:
1) Using GetCharTable - This function copies one or more
characters from the active table to a buffer. Beware that this
characters are always in a 32 scanlines format used by the
BIOS when a character table is active. So when you call
ModifyCharSet to restore them you must specify that they have
32 scanlines.
2) Using GetCharTableAddress - This function returns a far
pointer to one of the BIOS character definition tables stored
in ROM. You must specify which character table you desire
using constant defined in SCL1.H (GCA_8X8A, GCA_8X8B,
GCA_8X14, GCA_8X16). These character definitions cannot be
modified so they always have an original copy. Characters are
organized in these table in 8, 14 or 16 scanlines (the same
they are supposed to have).
To create new character definition you can use the SSG character
editor or draw a bitmap using Windows' PaintBrush program and using
the BMPCNV conversion utility (included as C source file in the
samples files) to create character definition out of the bitmap. In
this case you must create a bitmap of a size in pixels that is a
multiple of eight horizontally and 16, 14 or 8 vertically (depending
of the target character matrix).
Characters are displayed on the screen in 9 bits horizontal matrix.
The extra bit is normally set to the background color to make sure
that there is a separation between characters. In the case of ASCII
codes 0xC0 to 0xDF (used for graphic characters) the righmost pixel is
duplicated to make sure that characters are connected. If you want to
duplicate a bitmap image you must use characters 0xC0-0xDF. As you see
we're limited to the size of this bitmap. (You can also use BMPCNV to
view bitmaps in text mode).
Modifying Palette Colors
In text modes we have access to 16 different colors plus the border
color. The value of these colors is set by the BIOS to defaults each
time a video mode is set. Each color of this palette can have a value
of 0-63, so although we can only have 16 colors at one time on the
screen, we can select these 16 colors from a selection of 64 colors
using SCL1's ModifyPalette (modify all palette colors and border
color) or ModifyPaletteColor (modify one palette entry). Use SSG
Palette editor (Video Menu, Modify Palette) or take a look at the
SCL1DEMO Character and Palette under the Video Menu to see the
different colors available.
SCL1 Version 3.1 - Reference Manual - Page 310
REGISTRATION INFORMATION
SCL1 C function Library Version 3.1 is copyrighted by José Rodríguez
Alvira & José R. Lebrón. You don't have to pay any royalties to use
SCL1 in your programs. To Register as a SCL1 user and to obtain a copy
of SCL1 libraries for the Small, Medium, Compact, Large and Huge
memory models send $35.00 (or $70.00 to also get the source code) to:
José Rodríguez Alvira
El Monte Sur 190, Apt. B-342,
Hato Rey, Puerto Rico, 00918
You will receive by mail the latest version of the SCL1 library for
the compiler of your choice, and a free copy of a Full-Screen Extended
ASCII Editor called SSG, that generates the source code of your
screens using SCL1's functions (The SCL1DEMO was done with the help of
SSG). You will be notified of any future additions or revisions to
SCL1 and of any other program developed.
You are encouraged to share the Demo Distribution disk with your
friends. The full version that you obtain upon registration is not
intended for free distribution and should not be shared with others.
You can leave us a message through the Compuserve I.D. No. 70262,1562
or BIX Name jalvira.
The latest version of SCL1, sample programs and comments about these
programs are available in:
TECH BBS (Sysop: José Romero)
(809)731-2322
You do not have to be a registered member of this BBS to be able to
download SCL1 files. If you call for the first time, after you answer
the questionnaire you can locate SCL1 files in the FREE directory
under the FILES menu. Though new users have a 15 minutes per call
time restrictions, the files located in this directory can be
downloaded even if they take longer than 15 minutes to transfer. In
order to download more than one file use a batch type protocol.
You can leave any comments, suggestions or questions in this BBS
directed to JOSE ALVIRA or JOSE LEBRON. We will reply these messages
in the same BBS.
A german version of SCL1 is available from:
Michael Witte
Buchholzer Str. 8,
D-W-2116 Hanstedt
Germany
SCL1 Version 3.1 - Reference Manual - Page 311
Index
AddExtension . . . . . . . 5 EMS_Move . . . . . . . . . 43
BackgroundOff . . . . . . . 6 EMS_PageAdress . . . . . . 59
BackgroundOn . . . . . . . 9 EMS_Realloc . . . . . . . . 60
Beep . . . . . . . . . . . 9 EMS_RestorePageMap . . . . 61
BigCursor . . . . . . . . . 9 EMS_SavePageMap . . . . . . 62
Bin2Ascii . . . . . . . . . 10 EMS_SetHandleName . . . . . 63
Box . . . . . . . . . . . . 11 EMS_Status . . . . . . . . 64
Buf2Disk . . . . . . . . . 13 EMS_TotalLogPages . . . . . 65
C_SetUserLang . . . . . . . 30 EMS_Version . . . . . . . . 66
Calendar . . . . . . . . . 14 ErrorBox . . . . . . . . . 67
Center . . . . . . . . . . 17 ErrorShadowOff . . . . . . 68
ChangeDumpColor . . . . . . 17 ErrorShadowOn . . . . . . . 68
ChangeExtension . . . . . . 5 FB_SetUserLang . . . . . . 69
CheckChar . . . . . . . . . 18 FB3_SetUserLang . . . . . . 69
CheckEnhancedKeyb . . . . . 19 FieldCheck . . . . . . . . 70
CheckItemList . . . . . . . 21 Fields . . . . . . . . . . 71
CheckMouse . . . . . . . . 22 Fields2 . . . . . . . . . . 74
CheckMouseButton . . . . . 23 File2Buf . . . . . . . . . 96
ClearKeyBuf . . . . . . . . 24 FileBox . . . . . . . . . . 90
ClearWindow . . . . . . . . 25 FileBox2 . . . . . . . . . 91
ClockTick . . . . . . . . . 25 FileBox3 . . . . . . . . . 91
CloseFile . . . . . . . . . 26 FillBlock . . . . . . . . . 97
Cls . . . . . . . . . . . . 27 FindFirst . . . . . . . . . 98
CreateFile . . . . . . . . 28 FindNext . . . . . . . . . 98
CreateWindow . . . . . . . 29 GetCharSet . . . . . . . 101
CursorOff . . . . . . . . . 29 GetCharSetAddress . . . . 101
CursorOn . . . . . . . . . 29 GetCurCol . . . . . . . . 102
Date2Num . . . . . . . . . 31 GetCurLine . . . . . . . 102
DaysPerMonth . . . . . . . 32 GetCurrentDir . . . . . . 102
DeleteFile . . . . . . . . 32 GetCurSize . . . . . . . 103
DestroyWindow . . . . . . . 29 GetDate . . . . . . . . . 104
DialogBox . . . . . . . . . 33 GetDefaultDrive . . . . . 105
DisableMouse . . . . . . . 34 GetDiskFreeSpace . . . . 105
Dissolve . . . . . . . . . 34 GetExtendedAscii . . . . 106
DrawBoxLine . . . . . . . . 36 GetFileMode . . . . . . . 108
DrawItemList . . . . . . . 37 GetFilePt . . . . . . . . 109
DrawLine . . . . . . . . . 38 GetFiles . . . . . . . . 107
DrawMouseButton . . . . . . 39 GetFileSize . . . . . . . 111
EB_SetUserLang . . . . . . 40 GetFreeMem . . . . . . . 111
EMS_Alloc . . . . . . . . . 41 GetKey . . . . . . . . . 112
EMS_AvailableLogPages . . . 42 GetString . . . . . . . . 114
EMS_Exchange . . . . . . . 43 GetTime . . . . . . . . . 115
EMS_Free . . . . . . . . . 46 GSSBox . . . . . . . . . . 11
EMS_GetAllHandlePages . . . 47 HBuf2Disk . . . . . . . . . 13
EMS_GetHandleCount . . . . 48 HFile2Buf . . . . . . . . . 96
EMS_GetHandleName . . . . . 49 HideMouse . . . . . . . . 116
EMS_GetHandlePages . . . . 50 Huge2Far . . . . . . . . 115
EMS_Init . . . . . . . . . 51 I24_SetUserLang . . . . . 123
EMS_Map . . . . . . . . . . 57 InitDrive . . . . . . . . 117
EMS_MapMultipleEMS . . . . 58 InitMouse . . . . . . . . 117
SCL1 Version 3.1 - Reference Manual - Page 312
Index
InitUserError . . . . . . 118 PopMenu . . . . . . . . . 196
InitVideo . . . . . . . . 118 PushCursor . . . . . . . 194
InitWData . . . . . . . . 119 ReadFile . . . . . . . . 197
Int24ShadowOff . . . . . 122 ReadPalette . . . . . . . 198
Int24ShadowOn . . . . . . 122 RecordFile . . . . . . . 198
KeyReady . . . . . . . . 124 RemoveDir . . . . . . . . 202
KeyStatus . . . . . . . . 125 RemoveExtension . . . . . 202
LeapYear . . . . . . . . 127 RenameFile . . . . . . . 203
LineEditor . . . . . . . 128 ResetMouse . . . . . . . 204
LinkedList . . . . . . . 136 ResetMouseCur . . . . . . 204
ListManager . . . . . . . 140 RestoreInt10 . . . . . . 248
ListWindow . . . . . . . 142 ScreenDump . . . . . . . 205
LW_MoveTo . . . . . . . . 147 ScrollDown . . . . . . . 206
MakeDir . . . . . . . . . 160 ScrollList . . . . . . . 207
MCR_CloseFile . . . . . . 148 ScrollUp . . . . . . . . 206
MCR_Init . . . . . . . . 148 ScrollWindow . . . . . . 208
MCR_MacroDisable . . . . 153 Select . . . . . . . . . 214
MCR_MacroEnable . . . . . 153 SetBin2AsciiDel . . . . . 217
MCR_MacroExist . . . . . 153 SetCurPos . . . . . . . . 218
MCR_Play . . . . . . . . 154 SetCurSize . . . . . . . 218
MCR_ReadFile . . . . . . 154 SetDialogColor . . . . . 219
MCR_Record . . . . . . . 155 SetErrorBoxColor . . . . 219
MCR_RegisterBackF . . . . 155 SetFileMode . . . . . . . 220
MCR_RegisterMacro . . . . 156 SetHorLimit . . . . . . . 221
MCR_RegisterTrapKey . . . 157 SetInt24Colors . . . . . 222
MCR_Report . . . . . . . 157 SetMouseCur . . . . . . . 222
MCR_SaveMacro . . . . . . 158 SetMouseIsr . . . . . . . 222
MCR_UnregisterBackF . . . 159 SetMousePos . . . . . . . 224
MCR_UnregisterMacro . . . 159 SetShadowColor . . . . . 225
MCR_UnregisterTrapKey . . 159 SetUserBox . . . . . . . 225
Menu . . . . . . . . . . 161 SetUserBoxLine . . . . . 226
MenuSystem . . . . . . . 164 SetVerLimit . . . . . . . 221
MenuSystem2 . . . . . . . 164 SetVideo25 . . . . . . . 229
MESS_SetPosition . . . . 178 SetVideo28 . . . . . . . 229
MessageOff . . . . . . . 179 SetVideo4350 . . . . . . 229
MessageOn . . . . . . . . 180 SetVideoMode . . . . . . 227
MessageShadowOff . . . . 180 SetVideoPage . . . . . . 228
MessageShadowOn . . . . . 180 Shadow . . . . . . . . . 230
ModifyCharSet . . . . . . 182 ShellSort . . . . . . . . 231
ModifyPalette . . . . . . 184 ShowMouse . . . . . . . . 116
ModifyPaletteColor . . . 185 SortPointers . . . . . . 233
MouseButton . . . . . . . 187 Sound . . . . . . . . . . 234
MouseMenu . . . . . . . . 161 SoundOff . . . . . . . . 234
MouseMenu2 . . . . . . . 161 SoundOn . . . . . . . . . 234
MoveFilePt . . . . . . . 189 StopWatch . . . . . . . . 235
MoveFilePt2Offset . . . . 190 SW_MoveTo . . . . . . . . 147
Num2Date . . . . . . . . 190 TagItem . . . . . . . . . 236
OpenFile . . . . . . . . 191 TagList . . . . . . . . . 238
PercentBar . . . . . . . 193 TagList2 . . . . . . . . 240
PopCursor . . . . . . . . 194 TagMenu . . . . . . . . . 242
SCL1 Version 3.1 - Reference Manual - Page 313
Index
TextWindow . . . . . . . 245 ZWindow287
TL_SetUserLang . . . . . 248
TrapBIOSScreenWrite . . . 248
TrapInt10 . . . . . . . . 248
TrapInt23 . . . . . . . . 249
TrapInt24 . . . . . . . . 250
TSound . . . . . . . . . 251
Video . . . . . . . . . . 251
VideoConfig . . . . . . . 252
WaitKeyMouse . . . . . . 254
WaitTime . . . . . . . . 254
WF_SetUserLang . . . . . . 69
WFileBox . . . . . . . . . 91
Window . . . . . . . . . 254
WriteChar . . . . . . . . 256
WriteFile . . . . . . . . 257
WriteOffLen . . . . . . . 257
WriteOffset . . . . . . . 258
WriteScreen . . . . . . . 259
WriteScreenC . . . . . . 259
WriteScreenCLen . . . . . 260
WriteScreenLen . . . . . 260
WriteScreenR . . . . . . 259
WriteScreenRLen . . . . . 260
WriteWindow . . . . . . . 262
XMS_AllocExtended . . . . 263
XMS_FreeExtended . . . . 264
XMS_GetEMBHandleInfo . . 265
XMS_GetVersion . . . . . 266
XMS_GlobalDisableA20 . . 267
XMS_GlobalEnableA20 . . . 267
XMS_Init . . . . . . . . 268
XMS_LocalDisableA20 . . . 275
XMS_LocalEnableA20 . . . 275
XMS_LockExtended . . . . 276
XMS_MoveExtended . . . . 277
XMS_QueryA20 . . . . . . 278
XMS_QueryFreeExtended . . 279
XMS_ReallocExtended . . . 279
XMS_ReleaseHMA . . . . . 280
XMS_ReleaseUMB . . . . . 281
XMS_RequestHMA . . . . . 280
XMS_RequestUMB . . . . . 281
XMS_UnlockExtended . . . 282
YesNo . . . . . . . . . . 283
YesNoShadowOff . . . . . 284
YesNoShadowOn . . . . . . 284
YN_SetFrame . . . . . . . 286
YN_SetUserLang . . . . . 285
YNSetPosition . . . . . . 284
SCL1 Version 3.1 - Reference Manual - Page 314
